availability: Document how to check for single API calls

This documents how to use autotools and dlopen(3) to test for
the availability of single API calls at compile time and run time
respectively.

availability: Add a test for this call.

Because all the tested groups are optional, there's not really
a group we can reliably test, therefore test against the
empty list (which should not fail).

availability: Clarify and fix documentation.

generator: Passing "" to StringList tests should turn into empty list.

This is a bug in the generator which wasn't being tickled.  If
you had a test which expected a StringList or DeviceList parameter,
and you passed "" to that test, then you'd (probably) expect to be
testing an empty list, but in fact you got a single element list
containing an empty string.  This fixes it so you get an empty list.

daemon: Fix return value from aug_defnode.

Bug fix - the return value from this function was wrong
in the no-Augeas case.

Implement 'dd' command.

Use STRPREFIX instead of STREQLEN.

generator: second parameter to upload is Dev_or_Path, not String.

build: Add missing dependencies in perl directory

make all in the perl directory was missing a check that the library had been
built.

make check in the perl directory was missing a check that the appliance and test
images had been built.

build: Ensure building appliance depends on guestfsd

Previously, only the update.sh rule checked the daemon had been built. update.sh
is called directly from within make.sh, so in that path the dependency was never
checked. This adds the daemon dependency explicitly to the rebuild-from-scratch
path.

build: Don't re-check generator.ml for each generator_built in daemon directory

build: Rebuild the daemon as necessary from other directories

This change ensure that making the appliance will always rebuild the daemon if
required.

Update TODO file.

perl: Add Sys::Guestfs::Lib::feature_available

This is a nicer Perl wrapper around $g->available call.

Update the other code in Sys::Guestfs::Lib to use it before using
LVM, Augeas.

availability: Skip tests when functions are not available.

availability: Add optional groups and implement guestfs_available call.

The current groups are defined very conservatively using the
following criteria:
 (a) Would be impossible to implement on Windows because of
     sheer architectural differences (eg: mknod).
 (b) Already optional (augeas, inotify).
 (c) Not currently optional but not implemented on older RHEL and
     Debian releases (ntfs-3g.probe, scrub, zerofree).

The optional groups I've defined according to these criteria are:

 . augeas
 . inotify
 . linuxfsuuid
 . linuxmodules
 . linuxxattrs
 . lvm2
 . mknod
 . ntfs3g
 . scrub
 . selinux
 . zerofree

(Note that these choices don't prevent us from adding more
optional groups in future.  On the other hand to avoid breaking
ABIs we would not wish to change the above groups).

The rest of this large commit is really just implementation:

Each optional function is classified using Optional "group"
flag in the generator.

The daemon has to implement a function

  int optgroup_<name>_available (void);

for each optional group.  Some of these functions are fixed at
compile time, and some do simple run-time tests.

The do_available implementation in the daemon looks up the correct
function in a table and runs it.

We document the optional groups in the guestfs(3) man page.

Also: I added a NOT_AVAILABLE macro in order to unify all the
existing places where we had a message equivalent to
"function __func__ is not available".

availability: Add guestfs_available.

Start a new API allowing groups of functions to be tested for
availability.

There are two reasons for this:

(1) If libguestfs is built with missing dependencies (eg. no Augeas lib)
then the corresponding functions are disabled in the appliance.  Up till
now there has been no way to test for this except to speculatively
issue commands and check for errors.

(2) When we port the daemon to Win32 it is likely that major pieces of
functionality won't be available (eg. LVM support).  This API gives
a way to test for that.

There is no change for existing clients: you still have to check for
errors from individual API calls.

For new clients, you will be able to test for availability of particular
APIs.

Usage scenario (A): An LVM editing tool which requires
both the LVM API and inotify in order to function at all:

  char *apis[] = { "inotify", "lvm2", NULL };
  r = guestfs_available (g, apis);
  if (r == -1) {
    /* print an error and exit */
  }

Usage scenario (B): A general purpose tool which optionally provides
configuration file editing, but this can be disabled, the result
merely being reduced functionality:

  char *apis[] = { "augeas", NULL };
  r = guestfs_available (g, apis);
  enable_config_edit_menus = r == 0;

daemon/Win32: Use gnulib modules for first porting to Win32.

build: Add missing dependency libguestfs.la->guestfs_protocol.h

build: correct sed transformation to work also on .git-module-status

My patch was wrong.
I kept the sed transformation the same in the two places,
but it wasn't strict enough to also work on the file contents.
Sorry about that.  This fixes it.

>From 93927cc7b9f63c414e5bfeb7eba393fde3295601 Mon Sep 17 00:00:00 2001
From: Jim Meyering <meyering@redhat.com>
Date: Fri, 20 Nov 2009 16:23:17 +0100
Subject: [PATCH libguestfs] build: correct sed transformation to work also on .git-module-status

* autogen.sh: Use a more strict sed transformation so it works also
on the contents of .git-module-status, which has no prefix.
* cfg.mk (_submodule_hash): Use a stricter sed regexp.

build: make autogen.sh update .git-module-status, as it should

I ran autogen.sh, but then make was always failing like this:

    $ make
    cfg.mk:141: *** gnulib update required; run ./autogen.sh first.  Stop.

Here's the fix:

>From f743f32079fea2e8a17c7f5b59305e584c75dba0 Mon Sep 17 00:00:00 2001
From: Jim Meyering <meyering@redhat.com>
Date: Fri, 20 Nov 2009 14:29:55 +0100
Subject: [PATCH libguestfs] build: make autogen.sh update .git-module-status, as it should

* autogen.sh: Without this, "make" would always say "gnulib update
required; run ./autogen.sh first", even after you'd run autogen.sh
successfully.

maint: use EXIT_* symbol (not constant, 2) to indicate key/path not found

* hivex/hivexget.c (EXIT_NOT_FOUND): Define.
(main): Use exit (EXIT_NOT_FOUND), not "exit (2)".

maint: use EXIT_SUCCESS and EXIT_FAILURE, not 0 and 1 in "usage", too

Convert by running these commands:
perl -pi -e 's/\b(usage ?)\(1\)/$1(EXIT_FAILURE)/' \
  fish/fish.c fuse/guestmount.c
perl -pi -e 's/\b(usage ?)\(0\)/$1(EXIT_SUCCESS)/' \
  fish/fish.c fuse/guestmount.c
* fish/fish.c (main): Replace 0/1 with EXIT_SUCCESS/EXIT_FAILURE.
* fuse/guestmount.c (main): Likewise.

maint: use EXIT_SUCCESS and EXIT_FAILURE, not 0 and 1 to exit

Convert all uses automatically, via these two commands:
git grep -l '\<exit *(1)' \
  | grep -vEf .x-sc_prohibit_magic_number_exit \
  | xargs --no-run-if-empty \
    perl -pi -e 's/\b(exit ?)\(1\)/$1(EXIT_FAILURE)/'
git grep -l '\<exit *(0)' \
  | grep -vEf .x-sc_prohibit_magic_number_exit \
  | xargs --no-run-if-empty \
  perl -pi -e 's/\b(exit ?)\(0\)/$1(EXIT_SUCCESS)/'
* .x-sc_prohibit_magic_number_exit: New file.

Edit (RWMJ): Don't change Java code.

maint: remove unnecessary include of openat.h

* daemon/realpath.c: Don't include "openat.h".  not used.

build: update gnulib submodule to latest

daemon/gnulib: Include glob module.

daemon/Win32: Don't include missing headers.

This is a partial fix for code in guestfsd.c where many of these
header files are missing on Win32.

daemon/Win32: make some functions and fields optional.

inotify: Make this optional on platforms that don't have this interface.

mknod, mkfifo etc.: Make these optional on non-Unix platforms.

readdir: If d_type field is missing on the platform, set the corresponding
field to 'u'.

stat: st_blocks and st_blksize are missing on non-Unix platforms, so
set these fields to -1 in the corresponding structures.

daemon/Win32: NAME_MAX does not exist on Windows, use FILENAME_MAX instead.

daemon: Missing #includes revealed by cross-compiling.

daemon/Win32: Ignore mingw32-config.cache.

The Fedora Windows cross-compiler 'mingw32-configure' script always
uses a configure cache.  Ignore that file.

generator: open Unix module by default.

Add:

  open Unix

at the top of the generator, which means that we don't need to
prefix any 'Unix.foo' symbols (we can just use 'foo' instead).

Unfortunately the Unix module shadows one symbol in Pervasives
(the Pervasives module is opened by default in OCaml code).  That
symbol is 'stdout'.  So we replace this with 'Pervasives.stdout'
in two places.  Still a net reduction in code size.

syntax-check: Fix tab-vs-space issue in the generator.

Update PO files.

Update TODO file.

build: Fix parallel build of haskell bindings

ghc isn't clever enough not to stomp on itself when building dependencies. This
change makes the 1 dependency explicit.

It also adds a dependency on src/libguestfs.la.

build: Fix inter-directory dependencies

This change adds an explicit dependency on generator.ml for every file it
generates, except java files. Java is left for another time because it's
considerably trickier.

It also adds a build rule for src/libguestfs.la so it can be rebuilt as required
from other directories.

It does this by creating a top level make file, subdir-rules.mk, which can be
included from sub-directories. sub-directories need to define 'generator_built'
to include local files which are built by generator.ml, and they will be updated
automatically.

This fixes parallel make, and will automatically re-create generated files when
make is run from any directory.

It also fixes the problem which efad4f53 was targetting. Specifically,
src/guestfs_protocol.(c|h) had an erroneous dependency on stamp-generator, and
therefore generator.ml, despite not being directly created by it. This caused
them to be recreated every time generator.ml ran rather than only when
src/guestfs_protocol.x was updated, which cascaded into a daemon and therefore
appliance update.

This patch also changes the contents of the distribution tarball by including
files created by rpcgen.

generator: Acquire lock to prevent two parallel runs of the generator.

This commit acquires a lock on a file to prevent two parallel runs of
the generator from stomping on each other.  The second run will wait
for the first to complete before starting.

The lock is acquired on the "HACKING" file because it's convenient --
we are already checking this file exists to make sure that we don't
start off in the wrong directory.

Tested by adding some artificial sleeps in the code to observe
locking behaviour between two parallel runs.

syntax-check: expand TABs in generator.ml

Jim Meyering wrote:
>>From 6f128e90afb055f9899011c4a592eb289e678936 Mon Sep 17 00:00:00 2001
> From: Jim Meyering <meyering@redhat.com>
> Date: Thu, 19 Nov 2009 11:39:10 +0100
> Subject: [PATCH libguestfs] syntax-check: expand TABs in generator.ml
>
> * src/generator.ml: Expand leading TABs to spaces.

That was incomplete.
Please use the following instead.
With it, now, "make syntax-check" now passes once again.

>From 716a30d0b692972aac8fbea1fb7ad3318ab3a0d8 Mon Sep 17 00:00:00 2001
From: Jim Meyering <meyering@redhat.com>
Date: Thu, 19 Nov 2009 11:39:10 +0100
Subject: [PATCH libguestfs] syntax-check: expand leading TABs

* src/generator.ml: Expand leading TABs to spaces.
* fuse/test-fuse.sh: Likewise.

syntax-check: exempt *.pod from no-trailing-blank prohibition

* .x-sc_trailing_blank: Exempt *.pod.

BUILT_SOURCES now depends on running the generator.

This completely reverts commit efad4f53923dcca94613e193d6383bd032e70498.

daemon/RHEL: Choose correct udev settle script.

On RHEL/CentOS 5.4, udevadm settle command does not work.  This didn't
affect us before, but now that we're using parted for partitioning, we
*do* need to wait for udev to settle (because parted isn't waiting for
this, unlike sfdisk).

This commit chooses the correct program to run.

fuse/RHEL: Don't require UTIME_{NOW,OMIT} to be defined.

These macros don't exist on RHEL/CentOS 5.4.  If the feature
is missing then just don't implement it in the FUSE layer.

appliance: Print uptime.

Print the uptime just before the init script runs the daemon, so we
have a good idea of how long the kernel boot + init script takes to run.

recipes: Fix git URL.

Prepare for version 1.0.79.

fuse: Add test-fuse.sh to EXTRA_DIST.

generator: Fix API of functions that return RBufferOut

(NB: The API / ABI doesn't actually change here - it's just made much
simpler to use).

The API for RBufferOut functions was unexpectedly hard to use in the
case where a zero-length buffer might be returned.  For discussion on
this see:

https://www.redhat.com/archives/libguestfs/2009-November/thread.html#00115

This commit ensures that in the zero-length buffer case, the return
value is never NULL.  Thus code is now able to just check if the return
value == NULL to indicate an error, which is simpler for all concerned.

The implementation of this is, however, more complex because we have
to be careful about this case inside both the daemon and the library
code, which is what this commit does.

This has passed a full round of tests.

fuse: Add tests for guestmount.

This script contains non-exhaustive tests for the system calls
implemented by guestmount.

fuse: Fix read for empty files.

Error handling for the guestfs_pread call was incorrect, which
meant that empty files could produce spurious error messages.

fish: Improve output of guestfish -h cmd

Display this output like a short manual page.

Don't put <..> around the parameters to the command.

New API call: fill - fill a file with octets

fuse: Fix cache invalidation in rename operation.

We need to invalidate both parameters, otherwise the old (moved)
file can appear that it still exists after the move.

fuse: Fix hard link creation.

The parameters were swapped.  We also need to invalidate the
cache for both parameters.

fuse: Fix symlink creation (RHBZ#538069).

The parameters were swapped, preventing symlinks from being created.

virt-df: Ignore domains which have ID 0.

This is the remainder of the fix for RHBZ#538041.  Domains
which have ID 0 are special domains.  libvirt defines it as
the "control plane OS".  Only Xen and HyperV have this
behaviour, and in both cases we should ignore those domains
for the purposes of virt-df (user can just run "df" if they
need that information for the dom0).

virt-df: Turn errors into warnings when listing all domains.

This is a partial fix for RHBZ#538041.  When listing all domains,
don't die just because one domain fails, but keep trying for the
rest.

Docs: copyediting

Docs: Add documentation about other language bindings to API overview.

Docs: line folding in example.

Docs: group preformatted sections of text together.

Docs typo: limited -> limits

Docs: Add section on using multiple threads.

This section was missing from the previous documentation.

Docs: Add/extend API overview.

Docs: Remove incorrect statement from man page.

The low-level event-based API never existed so this statement
in the man page is wrong.  If you want an asynchronous API, use
threads.

build: revive the ocaml package tests

* autogen.sh: Generalize the ocaml-package-existence test.
Remove the git-related part of the old test.

Generate guestfs_protocol.x when stamp-generator updates

This partially reverts efad4f53923dcca94613e193d6383bd032e70498.
guestfs_protocol.x wasn't being generated when building from a clean checkout.

autogen.sh: Remove test for ocaml etc from this script.

This test seems to cause a lot of trouble.  We need to go back to
the drawing-board on this one.

Set cpio blocksize to 64K.

See:
https://www.redhat.com/archives/fedora-devel-list/2009-November/thread.html#00523

Debian: don't depend on gfs-tools since these have depsolving problems.

Update PO files for release.

Check for ocaml-xml-light-devel (xml-light.cmxa)

Also unquote $pkg since OCaml package names can never contain
spaces or other unfriendly characters.

Prepare for version 1.0.78

tell "make syntax-check" that examples/to-xml.c is exempt from some tests

* .x-sc_prohibit_strcmp: Exempt examples/to-xml.c.
* .x-sc_prohibit_strcmp_and_strncmp: Likewise.

examples: Don't use STREQ etc in the to-xml.c example.

Don't export STREQ and friends in <guestfs.h>

Move these to private header file(s) and other places as required
since these aren't part of the public API.

Fix problems found by 'make syntax check'

Print timestamped messages during appliance launch.

In verbose mode, print timestamped messages during guestfs_launch
so we can see how long each step takes.

Record time of guest launch.

The guest handle field start_t was previously used (when we
had the wait_ready call), but had fallen into disuse.  Note
that it could never be accessed through the API.

Rename this field as launch_t, convert it to a timeval, and
use it to measure the time since guestfs_launch was called
so that we can start profiling guest launch.

appliance: Prefix kernel messages with timestamp.

Generic partition creation interface.

This commit introduces a generic partition creation interface
which should be future-proof and extensible, and partially
replaces the old sfdisk-based interface.

The implementation is based on parted but is hopefully not too
dependent on the particulars of parted.

The following new calls are introduced:

  guestfs_part_init:
    Initialize a disk with a partition table.  Unlike the sfdisk-
    based interface, we also support GPT and other partition
    types, which is essential to scale to devices larger than 2TB.

  guestfs_part_add: Add a partition to an existing disk.

  guestfs_part_disk:
    Convenience function which combines part_init & part_add,
    creating a single partition that covers the whole disk.

  guestfs_part_set_bootable:
  guestfs_part_set_name:
    Set various aspects of existing partitions.

  guestfs_part_list:
    List partitions on a device.  This returns a programming-friendly
    list of partition structs (in contrast to sfdisk-l which cannot
    be parsed).

  guestfs_part_get_parttype:
    Return the partition table type, eg. "msdos" or "gpt".

The following calls are planned, but not added currently:

  guestfs_part_get_bootable
  guestfs_part_get_name
  guestfs_part_set_type
  guestfs_part_get_type

Add ata_piix to kernel module whitelist (RHBZ#533886).

Fix compilation if readline library is not present.

Fix compilation when Augeas is not present.

It would complain that NEED_AUG macro was defined but not used.

avoid "syntax-check" failure: hide cast of argument to free

* fuse/guestmount.c (fg_readlink): Perform cast in a
 separate statement to hide it from "make syntax-check".

build: die early if we lack ocaml, ocamlfind or ocaml-xml-light

* autogen.sh: Ensure that we fail very early when not building
from a tarball and when one of those is not installed.

tests: enable strcmp-related syntax-check tests

* cfg.mk (local-checks-to-skip): Don't skip these checks:
sc_prohibit_strcmp_and_strncmp, sc_prohibit_strcmp.

change strncasecmp() == 0 to STRCASEEQLEN()

git grep -l 'strncasecmp *([^=]*== *0'|xargs \
  perl -pi -e 's/\bstrncasecmp( *\(.*?\)) *== *0\b/STRCASEEQLEN$1/g'

change strncasecmp() == 0 to STRCASENEQLEN()

git grep -l 'strncasecmp *([^=]*!= *0'|xargs \
  perl -pi -e 's/\bstrncasecmp( *\(.*?\)) *!= *0\b/STRCASENEQLEN$1/g'

use STREQ, not strcmp: part 2

git grep -l 'strcmp *([^=]*!= *0'|xargs \
  perl -pi -e 's/\bstrcmp( *\(.*?\)) *!= *0\b/STRNEQ$1/g'

use STREQ, not strcmp: part 1

git grep -l 'strcmp *([^=]*== *0'|xargs \
  perl -pi -e 's/\bstrcmp( *\(.*?\)) *== *0/STREQ$1/g'

change strncmp() == 0 to STREQLEN()

git grep -l 'strncmp *([^=]*== *0'|xargs \
  perl -pi -e 's/\bstrncmp( *\(.*?\)) *== *0\b/STREQLEN$1/g'

change strncmp(...) != 0 to STRNEQLEN(...)

git grep -l 'strncmp *([^=]*!= *0'|xargs \
  perl -pi -e 's/\bstrncmp( *\(.*?\)) *!= *0/STRNEQLEN$1/g'

convert strcasecmp(...) != 0 to STRCASENEQ(...)

git grep -E -l 'strcasecmp *\(.*!= ?0\b'|xargs \
  perl -pi -e 's/\bstrcasecmp( ?\(.*?\)) != 0/STRCASENEQ$1/g'

convert uses of strcasecmp to STRCASEEQ

git grep -l 'strcasecmp *([^=]*== *0'| xargs \
  perl -pi -e 's/\bstrcasecmp( *\(.*?\)) *== *0/STRCASEEQ$1/'

define STREQ, STRNEQ, STREQLEN, STRCASEQ, etc.

* src/guestfs.h: Define STREQ and company.
* daemon/daemon.h: Likewise.
* hivex/hivex.h: Likewise.

indent with spaces, not TABs

* HACKING: Expand indentation TABs.
* configure.ac: Likewise.
* daemon/daemon.h: Likewise.
* daemon/guestfsd.c: Likewise.
* fuse/guestmount.c: Likewise.
* hivex/LICENSE: Likewise.
* src/generator.ml: Likewise.
* tools/virt-win-reg: Likewise.

fix doc typo

* fuse/guestmount.pod: Avoid "the the".

placate 'make syntax-check'

* hivex/hivex.c: Remove unused "#include <assert.h>".