The former documentation was an unhelpful tautology. The suggested doc
borrows the wording from virDomainSetAutostart.
Signed-off-by: NDan Kenigsberg <danken@redhat.com>
Reviewed-by: NErik Skultety <eskultet@redhat.com>

Whenever we declare a new object the first member of the struct
has to be virObject (or any other member of that family). Now, up
until now we did not care about the name of the struct member.
But lets unify it so that we can do some checks at compile time
later.

The unified name is 'parent'.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>
Reviewed-by: NErik Skultety <eskultet@redhat.com>
Reviewed-by: NDaniel P. Berrangé <berrange@redhat.com>

The storagePoolLookupByTargetPath() method in the storage driver is used
by the QEMU driver during block migration. If there's a valid use case
for this in the QEMU driver, then external apps likely have similar
needs. Exposing it in the public API removes the direct dependancy from
the QEMU driver to the storage driver.
Signed-off-by: NDaniel P. Berrangé <berrange@redhat.com>

Resolve a storage driver crash as a result of a long running
storageVolCreateXML when the virStorageVolPoolRefreshThread is
run as a result of when a storageVolUpload completed and ran the
virStoragePoolObjClearVols without checking if the creation
code was currently processing a buildVol after incrementing
the driver->asyncjob count.

The refreshThread will now check the pool asyncjob count before
attempting to pursue the pool refresh. Adjust the documentation
to describe the condition.

Crash from valgrind is as follows (with a bit of editing):

==21309== Invalid read of size 8
==21309==    at 0x153E47AF: storageBackendUpdateVolTargetInfo
==21309==    by 0x153E4C30: virStorageBackendUpdateVolInfo
==21309==    by 0x153E52DE: virStorageBackendVolRefreshLocal
==21309==    by 0x153DE29E: storageVolCreateXML
==21309==    by 0x562035B: virStorageVolCreateXML
==21309==    by 0x147366: remoteDispatchStorageVolCreateXML
...
==21309==  Address 0x2590a720 is 64 bytes inside a block of size 336 free'd
==21309==    at 0x4C2F2BB: free
==21309==    by 0x54CB9FA: virFree
==21309==    by 0x55BC800: virStorageVolDefFree
==21309==    by 0x55BF1D8: virStoragePoolObjClearVols
==21309==    by 0x153D967E: virStorageVolPoolRefreshThread
...
==21309==  Block was alloc'd at
==21309==    at 0x4C300A5: calloc
==21309==    by 0x54CB483: virAlloc
==21309==    by 0x55BDC1F: virStorageVolDefParseXML
==21309==    by 0x55BDC1F: virStorageVolDefParseNode
==21309==    by 0x55BE5A4: virStorageVolDefParse
==21309==    by 0x153DDFF1: storageVolCreateXML
==21309==    by 0x562035B: virStorageVolCreateXML
==21309==    by 0x147366: remoteDispatchStorageVolCreateXML
...

Seeing a log message saying 'flags=93' is ambiguous & confusing unless
you happen to know that libvirt always prints flags as hex.  Change our
debug messages so that they always add a '0x' prefix when printing flags,
and '0' prefix when printing mode. A few other misc places gain a '0x'
prefix in error messages too.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

The API docs for the various vir$OBJECTGetConnect functions
contain a warning

  WARNING: When writing libvirt bindings in other languages, do
  not use this function.  Instead, store the connection and
  the domain object together.

There is no reason why language bindings should not use this
method, and indeed the Perl, Python, and Go bindings all use
these methods.

This warning was originally added back in

  commit 3edb4bc9
  Author: Daniel Veillard <veillard@redhat.com>
  Date:   Tue Jul 24 15:32:55 2007 +0000

    * libvirt.spec.in NEWS docs/* po/*: preparing release 0.3.1
    * src/libvirt.c python/generator.py: some cleanup and warnings
      from Richard W.M. Jones

IIUC, the rational was that these APIs do not need to be
directly exposed to the non-C language, as the language
can expose the same concept itself by storing the original
virConnectPtr object alongside the virDomainPtr.  There's
no reason to mandate such an approach though - it is valid
for languages to expose this directly if that suits their
needs better.
Signed-off-by: NDaniel P. Berrange <berrange@redhat.com>

These flags to APIs will tell if caller wants to use sparse
stream for storage transfer. At the same time, it's safe to
enable them in storage driver frontend and rely on our backends
checking the flags. This way we can enable specific flags only on
some specific backends, e.g. enable
VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM for filesystem backend but
not iSCSI backend.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>

https://bugzilla.redhat.com/show_bug.cgi?id=1332019

This function will essentially be a wrapper to virStorageVolInfo in order
to provide a mechanism to have the "physical" size of the volume returned
instead of the "allocation" size. This will provide similar capabilities to
the virDomainBlockInfo which can return both allocation and physical of a
domain storage volume.

NB: Since we're reusing the _virStorageVolInfo and not creating a new
_virStorageVolInfoFlags structure, we'll need to generate the rpc APIs
remoteStorageVolGetInfoFlags and remoteDispatchStorageVolGetInfoFlags
(although both were originally created from gendispatch.pl and then
just copied into daemon/remote.c and src/remote/remote_driver.c).

The new API will allow the usage of a VIR_STORAGE_VOL_GET_PHYSICAL flag
and will make the decision to return the physical or allocation value
into the allocation field.

In order to get that physical value, virStorageBackendUpdateVolTargetInfoFD
adds logic to fill in physical value matching logic in qemuStorageLimitsRefresh
used by virDomainBlockInfo when the domain is inactive.
Signed-off-by: NJohn Ferlan <jferlan@redhat.com>

When wiping a volume we just rewrite all the data of the volume, not
only the content.  Since format gets overridden, we need to recreate the
volume.  However we can't do that for every possible format out there.
Since it was only coded for the ploop volume type, let's document what
might be the consequences instead of forbidding it for every other
format out there.

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=868771Signed-off-by: NMartin Kletzander <mkletzan@redhat.com>

Storage pool lifecycle event API entry points for registering and deregistering
storage pool events, as well as types of events associated with storage pools.
These entry points will be used for implementing asynchronous lifecycle events.

Storage pool API:
virConnectStoragePoolEventRegisterAny
virConnectStoragePoolEventDeregisterAny
virStoragePoolEventLifecycleType which has events STARTED, STOPPED, DEFINED,
UNDEFINED, and REFRESHED

So you have a libvirt volume that you want to wipe out. But lets
say that the volume is actually a file stored on a journaled
filesystem. Overwriting it with zeroes or a pattern does not mean
that corresponding physical location on the disk is overwritten
too, due to journaling. It's the same story with network based
volumes, copy-on-write filesystems, and so on. Since there is no
way that an userland application can write onto specific areas on
disk, all that we can do is document the fact.
Signed-off-by: NMichal Privoznik <mprivozn@redhat.com>

Although they've been present for quite a while, they weren't added
to the API definition, so add them there to make it clearer.

Currently only the RBD backend even checks for any flags.

https://bugzilla.redhat.com/show_bug.cgi?id=830056

Add flags handling to the virStoragePoolCreate and virStoragePoolCreateXML
API's which will allow the caller to provide the capability for the storage
pool create API's to also perform a pool build during creation rather than
requiring the additional buildPool step. This will allow transient pools
to be defined, built, and started.

The new flags are:

    * VIR_STORAGE_POOL_CREATE_WITH_BUILD
      Perform buildPool without any flags passed.

    * VIR_STORAGE_POOL_CREATE_WITH_BUILD_OVERWRITE
      Perform buildPool using VIR_STORAGE_POOL_BUILD_OVERWRITE flag.

    * VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE
      Perform buildPool using VIR_STORAGE_POOL_BUILD_NO_OVERWRITE flag.

It is up to the backend to handle the processing of build flags. The
overwrite and no-overwrite flags are mutually exclusive.

NB:
This patch is loosely based upon code originally authored by Osier
Yang that were not reviewed and pushed, see:

https://www.redhat.com/archives/libvir-list/2012-July/msg01328.html

There are also a couple that were very uninformatively just logging
the value of the pointer rather than the string itself:

* the "name" arg to virNodeDeviceLookupByName()
* wwnn and wwpn args to virNodeDeviceLookupSCSIHostByWWN()

All char*'s that make sense should now have their contents logged
rather than the pointer, and all %s args should now be inside
NULLSTR().

Resolves: https://bugzilla.redhat.com/show_bug.cgi?id=1127045Signed-off-by: NPavel Hrdina <phrdina@redhat.com>

Signed-off-by: NMartin Kletzander <mkletzan@redhat.com>

Introduce a src/libvirt-storage.c file to hold all the
methods related to the virStorage{Pool,Vol} types.