We should allow strings (not the functions) in the format of "virDomainFree" and friends. This fixes an error in latter commit "scripts: apibuild: parse 'Since' for functions" as it uses this function names as keys in a dictionary. Fixes: | ... | prohibit_virXXXFree | libvirt/scripts/apibuild.py:163: 'virDomainFree': '0.0.1', | make: Leaving directory '/home/toso/src/libvirt/build/build-aux' | stderr: | build-aux/syntax-check.mk: avoid using virXXXFree, use virObjectUnref instead | make: *** [libvirt/build-aux/syntax-check.mk:829: sc_prohibit_virXXXFree] Error 1 Signed-off-by: Victor Toso <victortoso@redhat.com> --- build-aux/syntax-check.mk | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/build-aux/syntax-check.mk b/build-aux/syntax-check.mk index eb403f3d3f..07e0295995 100644 --- a/build-aux/syntax-check.mk +++ b/build-aux/syntax-check.mk @@ -827,7 +827,7 @@ sc_prohibit_system_error_with_vir_err: # docs, examples, tools, src/libvirt-*.c, and include/libvirt/libvirt-*.h sc_prohibit_virXXXFree: @prohibit='\bvir(Domain|Network|NodeDevice|StorageVol|StoragePool|Stream|Secret|NWFilter|Interface|DomainSnapshot)Free\b' \ - exclude='sc_prohibit_virXXXFree' \ + exclude="sc_prohibit_virXXXFree|'vir.*?Free'" \ halt='avoid using virXXXFree, use virObjectUnref instead' \ $(_sc_search_regexp) -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given enum value was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso@redhat.com> --- include/libvirt/libvirt-qemu.h | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/include/libvirt/libvirt-qemu.h b/include/libvirt/libvirt-qemu.h index 98f2ac3823..a2569a9fbd 100644 --- a/include/libvirt/libvirt-qemu.h +++ b/include/libvirt/libvirt-qemu.h @@ -31,8 +31,8 @@ extern "C" { # endif typedef enum { - VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT = 0, - VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP = (1 << 0), /* cmd is in HMP */ + VIR_DOMAIN_QEMU_MONITOR_COMMAND_DEFAULT = 0, /* (Since: v0.8.8) */ + VIR_DOMAIN_QEMU_MONITOR_COMMAND_HMP = (1 << 0), /* cmd is in HMP (Since: v0.8.8) */ } virDomainQemuMonitorCommandFlags; int virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd, @@ -51,11 +51,11 @@ virDomainPtr virDomainQemuAttach(virConnectPtr domain, unsigned int flags); typedef enum { - VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, - VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, - VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT, - VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT, - VIR_DOMAIN_QEMU_AGENT_COMMAND_SHUTDOWN = 60, + VIR_DOMAIN_QEMU_AGENT_COMMAND_MIN = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, /* (Since: v0.10.0) */ + VIR_DOMAIN_QEMU_AGENT_COMMAND_BLOCK = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK, /* (Since: v0.10.0) */ + VIR_DOMAIN_QEMU_AGENT_COMMAND_DEFAULT = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT, /* (Since: v0.10.0) */ + VIR_DOMAIN_QEMU_AGENT_COMMAND_NOWAIT = VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_NOWAIT, /* (Since: v0.10.0) */ + VIR_DOMAIN_QEMU_AGENT_COMMAND_SHUTDOWN = 60, /* (Since: v1.2.15) */ } virDomainQemuAgentCommandTimeoutValues; char *virDomainQemuAgentCommand(virDomainPtr domain, const char *cmd, @@ -85,10 +85,10 @@ typedef void (*virConnectDomainQemuMonitorEventCallback)(virConnectPtr conn, typedef enum { - /* Event filter is a regex rather than a literal string */ + /* Event filter is a regex rather than a literal string (Since: v1.2.3) */ VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_REGEX = (1 << 0), - /* Event filter is case insensitive */ + /* Event filter is case insensitive (Since: v1.2.3) */ VIR_CONNECT_DOMAIN_QEMU_MONITOR_EVENT_REGISTER_NOCASE = (1 << 1), } virConnectDomainQemuMonitorEventRegisterFlags; -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given enum value was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso@redhat.com> --- include/libvirt/libvirt-admin.h | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/include/libvirt/libvirt-admin.h b/include/libvirt/libvirt-admin.h index e414f776e4..f65886f20d 100644 --- a/include/libvirt/libvirt-admin.h +++ b/include/libvirt/libvirt-admin.h @@ -205,12 +205,12 @@ int virAdmClientGetTransport(virAdmClientPtr client); int virAdmClientFree(virAdmClientPtr client); typedef enum { - VIR_CLIENT_TRANS_UNIX = 0, /* connection via UNIX socket */ - VIR_CLIENT_TRANS_TCP, /* connection via unencrypted TCP socket */ - VIR_CLIENT_TRANS_TLS, /* connection via encrypted TCP socket */ + VIR_CLIENT_TRANS_UNIX = 0, /* connection via UNIX socket (Since: v1.3.5) */ + VIR_CLIENT_TRANS_TCP, /* connection via unencrypted TCP socket (Since: v1.3.5) */ + VIR_CLIENT_TRANS_TLS, /* connection via encrypted TCP socket (Since: v1.3.5) */ # ifdef VIR_ENUM_SENTINELS - VIR_CLIENT_TRANS_LAST + VIR_CLIENT_TRANS_LAST /* (Since: v1.3.5) */ # endif } virClientTransport; -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given macro was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso@redhat.com> --- include/libvirt/libvirt-domain.h | 663 +++++++++++++++++++++++++++++- include/libvirt/libvirt-host.h | 123 ++++++ include/libvirt/libvirt-network.h | 24 ++ include/libvirt/libvirt-nodedev.h | 3 + include/libvirt/libvirt-secret.h | 3 + include/libvirt/libvirt-storage.h | 3 + 6 files changed, 810 insertions(+), 9 deletions(-) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index de2d14d4af..01ea2a750f 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -315,6 +315,9 @@ typedef enum { * * Macro represents proportional weight of the scheduler used on the * host cpu, when using the posix scheduler, as a ullong. + * + * Since: v0.9.7 + * */ # define VIR_DOMAIN_SCHEDULER_CPU_SHARES "cpu_shares" @@ -323,6 +326,9 @@ typedef enum { * * Macro represents the enforcement period for a quota, in microseconds, * for whole domain, when using the posix scheduler, as a ullong. + * + * Since: v1.3.3 + * */ # define VIR_DOMAIN_SCHEDULER_GLOBAL_PERIOD "global_period" @@ -331,6 +337,9 @@ typedef enum { * * Macro represents the maximum bandwidth to be used within a period for * whole domain, when using the posix scheduler, as an llong. + * + * Since: v1.3.3 + * */ # define VIR_DOMAIN_SCHEDULER_GLOBAL_QUOTA "global_quota" @@ -339,6 +348,9 @@ typedef enum { * * Macro represents the enforcement period for a quota, in microseconds, * for vcpus only, when using the posix scheduler, as a ullong. + * + * Since: v0.9.7 + * */ # define VIR_DOMAIN_SCHEDULER_VCPU_PERIOD "vcpu_period" @@ -347,6 +359,9 @@ typedef enum { * * Macro represents the maximum bandwidth to be used within a period for * vcpus only, when using the posix scheduler, as an llong. + * + * Since: v0.9.7 + * */ # define VIR_DOMAIN_SCHEDULER_VCPU_QUOTA "vcpu_quota" @@ -356,6 +371,9 @@ typedef enum { * Macro represents the enforcement period for a quota in microseconds, * when using the posix scheduler, for all emulator activity not tied to * vcpus, as a ullong. + * + * Since: v0.10.0 + * */ # define VIR_DOMAIN_SCHEDULER_EMULATOR_PERIOD "emulator_period" @@ -365,6 +383,9 @@ typedef enum { * Macro represents the maximum bandwidth to be used within a period for * all emulator activity not tied to vcpus, when using the posix scheduler, * as an llong. + * + * Since: v0.10.0 + * */ # define VIR_DOMAIN_SCHEDULER_EMULATOR_QUOTA "emulator_quota" @@ -373,6 +394,9 @@ typedef enum { * * Macro represents the enforcement period for a quota, in microseconds, * for IOThreads only, when using the posix scheduler, as a ullong. + * + * Since: v2.2.0 + * */ # define VIR_DOMAIN_SCHEDULER_IOTHREAD_PERIOD "iothread_period" @@ -381,6 +405,9 @@ typedef enum { * * Macro represents the maximum bandwidth to be used within a period for * IOThreads only, when using the posix scheduler, as an llong. + * + * Since: v2.2.0 + * */ # define VIR_DOMAIN_SCHEDULER_IOTHREAD_QUOTA "iothread_quota" @@ -389,6 +416,9 @@ typedef enum { * * Macro represents the relative weight, when using the credit * scheduler, as a uint. + * + * Since: v0.9.7 + * */ # define VIR_DOMAIN_SCHEDULER_WEIGHT "weight" @@ -397,6 +427,9 @@ typedef enum { * * Macro represents the maximum scheduler cap, when using the credit * scheduler, as a uint. + * + * Since: v0.9.7 + * */ # define VIR_DOMAIN_SCHEDULER_CAP "cap" @@ -405,6 +438,9 @@ typedef enum { * * Macro represents the scheduler reservation value, when using the * allocation scheduler, as an llong. + * + * Since: v0.9.7 + * */ # define VIR_DOMAIN_SCHEDULER_RESERVATION "reservation" @@ -413,6 +449,9 @@ typedef enum { * * Macro represents the scheduler limit value, when using the * allocation scheduler, as an llong. + * + * Since: v0.9.7 + * */ # define VIR_DOMAIN_SCHEDULER_LIMIT "limit" @@ -421,6 +460,9 @@ typedef enum { * * Macro represents the scheduler shares value, when using the * allocation scheduler, as an int. + * + * Since: v0.9.7 + * */ # define VIR_DOMAIN_SCHEDULER_SHARES "shares" @@ -479,6 +521,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * * Macro providing the field length of parameter names when using * virDomainBlockStatsFlags(). + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH @@ -487,6 +532,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * * Macro represents the total number of read bytes of the * block device, as an llong. + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_READ_BYTES "rd_bytes" @@ -495,6 +543,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * * Macro represents the total read requests of the * block device, as an llong. + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_READ_REQ "rd_operations" @@ -503,6 +554,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * * Macro represents the total time spend on cache reads in * nano-seconds of the block device, as an llong. + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_READ_TOTAL_TIMES "rd_total_times" @@ -511,6 +565,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * * Macro represents the total number of write bytes of the * block device, as an llong. + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_WRITE_BYTES "wr_bytes" @@ -519,6 +576,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * * Macro represents the total write requests of the * block device, as an llong. + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_WRITE_REQ "wr_operations" @@ -527,6 +587,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * * Macro represents the total time spend on cache writes in * nano-seconds of the block device, as an llong. + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_WRITE_TOTAL_TIMES "wr_total_times" @@ -535,6 +598,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * * Macro represents the total flush requests of the * block device, as an llong. + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_FLUSH_REQ "flush_operations" @@ -543,6 +609,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * * Macro represents the total time spend on cache flushing in * nano-seconds of the block device, as an llong. + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_FLUSH_TOTAL_TIMES "flush_total_times" @@ -550,6 +619,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * VIR_DOMAIN_BLOCK_STATS_ERRS: * * In Xen this returns the mysterious 'oo_req', as an llong. + * + * Since: v0.9.5 + * */ # define VIR_DOMAIN_BLOCK_STATS_ERRS "errs" @@ -977,6 +1049,9 @@ typedef enum { * required to transmit migration data. * * This field may not be used when VIR_MIGRATE_TUNNELLED flag is set. + * + * Since: v1.1.0 + * */ # define VIR_MIGRATE_PARAM_URI "migrate_uri" @@ -987,6 +1062,9 @@ typedef enum { * destination host as VIR_TYPED_PARAM_STRING. Omitting this parameter keeps * the domain name the same. This field is only allowed to be used with * hypervisors that support domain renaming during migration. + * + * Since: v1.1.0 + * */ # define VIR_MIGRATE_PARAM_DEST_NAME "destination_name" @@ -1006,6 +1084,9 @@ typedef enum { * Omitting this parameter keeps the original domain configuration. Using this * field with hypervisors that do not support changing domain configuration * during migration will result in a failure. + * + * Since: v1.1.0 + * */ # define VIR_MIGRATE_PARAM_DEST_XML "destination_xml" @@ -1021,6 +1102,9 @@ typedef enum { * Omitting this parameter keeps the original domain persistent configuration. * Using this field with hypervisors that do not support changing domain * configuration during migration will result in a failure. + * + * Since: v1.3.4 + * */ # define VIR_MIGRATE_PARAM_PERSIST_XML "persistent_xml" @@ -1031,6 +1115,9 @@ typedef enum { * be used for migration as VIR_TYPED_PARAM_ULLONG. If set to 0 or omitted, * libvirt will choose a suitable default. Some hypervisors do not support this * feature and will return an error if this field is used and is not 0. + * + * Since: v1.1.0 + * */ # define VIR_MIGRATE_PARAM_BANDWIDTH "bandwidth" @@ -1040,6 +1127,9 @@ typedef enum { * virDomainMigrate* params field: the maximum bandwidth (in MiB/s) that will * be used for post-copy phase of a migration as VIR_TYPED_PARAM_ULLONG. If set * to 0 or omitted, post-copy migration speed will not be limited. + * + * Since: v5.1.0 + * */ # define VIR_MIGRATE_PARAM_BANDWIDTH_POSTCOPY "bandwidth.postcopy" @@ -1061,6 +1151,9 @@ typedef enum { * parameters are "tlsPort" and "tlsSubject". For example, * * spice://target.host.com:1234/?tlsPort=4567 + * + * Since: v1.1.0 + * */ # define VIR_MIGRATE_PARAM_GRAPHICS_URI "graphics_uri" @@ -1072,6 +1165,9 @@ typedef enum { * addresses are accepted as well as hostnames (the resolving is done on * destination). Some hypervisors do not support this feature and will return * an error if this field is used. + * + * Since: v1.1.4 + * */ # define VIR_MIGRATE_PARAM_LISTEN_ADDRESS "listen_address" @@ -1081,6 +1177,9 @@ typedef enum { * virDomainMigrate* params multiple field: The multiple values that list * the block devices to be migrated. At the moment this is only supported * by the QEMU driver but not for the tunnelled migration. + * + * Since: v1.2.17 + * */ # define VIR_MIGRATE_PARAM_MIGRATE_DISKS "migrate_disks" @@ -1091,6 +1190,9 @@ typedef enum { * for incoming disks migration. Type is VIR_TYPED_PARAM_INT. If set to 0 or * omitted, libvirt will choose a suitable default. At the moment this is only * supported by the QEMU driver. + * + * Since: v1.3.3 + * */ # define VIR_MIGRATE_PARAM_DISKS_PORT "disks_port" @@ -1104,6 +1206,9 @@ typedef enum { * currently only supported by the QEMU driver. UNIX URI is only usable if the * management application makes sure that socket created with this name on the * destination will be reachable from the source under the same exact path. + * + * Since: v6.8.0 + * */ # define VIR_MIGRATE_PARAM_DISKS_URI "disks_uri" @@ -1114,6 +1219,9 @@ typedef enum { * compress migration traffic. Supported compression methods: xbzrle, mt. * The parameter may be specified multiple times if more than one method * should be used. + * + * Since: v1.3.4 + * */ # define VIR_MIGRATE_PARAM_COMPRESSION "compression" @@ -1123,6 +1231,9 @@ typedef enum { * virDomainMigrate* params field: the level of compression for multithread * compression as VIR_TYPED_PARAM_INT. Accepted values are in range 0-9. * 0 is no compression, 1 is maximum speed and 9 is maximum compression. + * + * Since: v1.3.4 + * */ # define VIR_MIGRATE_PARAM_COMPRESSION_MT_LEVEL "compression.mt.level" @@ -1131,6 +1242,9 @@ typedef enum { * * virDomainMigrate* params field: the number of compression threads for * multithread compression as VIR_TYPED_PARAM_INT. + * + * Since: v1.3.4 + * */ # define VIR_MIGRATE_PARAM_COMPRESSION_MT_THREADS "compression.mt.threads" @@ -1139,6 +1253,9 @@ typedef enum { * * virDomainMigrate* params field: the number of decompression threads for * multithread compression as VIR_TYPED_PARAM_INT. + * + * Since: v1.3.4 + * */ # define VIR_MIGRATE_PARAM_COMPRESSION_MT_DTHREADS "compression.mt.dthreads" @@ -1147,6 +1264,9 @@ typedef enum { * * virDomainMigrate* params field: the size of page cache for xbzrle * compression as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.3.4 + * */ # define VIR_MIGRATE_PARAM_COMPRESSION_XBZRLE_CACHE "compression.xbzrle.cache" @@ -1156,6 +1276,9 @@ typedef enum { * virDomainMigrate* params field: the initial percentage guest CPUs are * throttled to when auto-convergence decides migration is not converging. * As VIR_TYPED_PARAM_INT. + * + * Since: v2.0.0 + * */ # define VIR_MIGRATE_PARAM_AUTO_CONVERGE_INITIAL "auto_converge.initial" @@ -1166,6 +1289,9 @@ typedef enum { * VIR_MIGRATE_PARAM_AUTO_CONVERGE_INITIAL whenever the hypervisor decides * the current rate is not enough to ensure convergence of the migration. * As VIR_TYPED_PARAM_INT. + * + * Since: v2.0.0 + * */ # define VIR_MIGRATE_PARAM_AUTO_CONVERGE_INCREMENT "auto_converge.increment" @@ -1174,6 +1300,9 @@ typedef enum { * * virDomainMigrate* params field: number of connections used during parallel * migration. As VIR_TYPED_PARAM_INT. + * + * Since: v5.2.0 + * */ # define VIR_MIGRATE_PARAM_PARALLEL_CONNECTIONS "parallel.connections" @@ -1188,6 +1317,9 @@ typedef enum { * the destination hostname and the expected certificate's hostname is known, * this parameter can be used to pass this expected hostname when starting * the migration. + * + * Since: v6.0.0 + * */ # define VIR_MIGRATE_PARAM_TLS_DESTINATION "tls.destination" @@ -1450,18 +1582,27 @@ int virDomainGetState (virDomainPtr domain, * VIR_DOMAIN_CPU_STATS_CPUTIME: * cpu usage (sum of both vcpu and hypervisor usage) in nanoseconds, * as a ullong + * + * Since: v0.9.10 + * */ # define VIR_DOMAIN_CPU_STATS_CPUTIME "cpu_time" /** * VIR_DOMAIN_CPU_STATS_USERTIME: * cpu time charged to user instructions in nanoseconds, as a ullong + * + * Since: v0.9.11 + * */ # define VIR_DOMAIN_CPU_STATS_USERTIME "user_time" /** * VIR_DOMAIN_CPU_STATS_SYSTEMTIME: * cpu time charged to system instructions in nanoseconds, as a ullong + * + * Since: v0.9.11 + * */ # define VIR_DOMAIN_CPU_STATS_SYSTEMTIME "system_time" @@ -1469,6 +1610,9 @@ int virDomainGetState (virDomainPtr domain, * VIR_DOMAIN_CPU_STATS_VCPUTIME: * vcpu usage in nanoseconds (cpu_time excluding hypervisor time), * as a ullong + * + * Since: v0.9.13 + * */ # define VIR_DOMAIN_CPU_STATS_VCPUTIME "vcpu_time" @@ -1497,6 +1641,9 @@ char * virDomainGetSchedulerType(virDomainPtr domain, * * Macro for the Blkio tunable weight: it represents the io weight * the guest can use, as a uint. + * + * Since: v0.9.0 + * */ # define VIR_DOMAIN_BLKIO_WEIGHT "weight" @@ -1507,6 +1654,9 @@ char * virDomainGetSchedulerType(virDomainPtr domain, * Macro for the blkio tunable weight_device: it represents the * per-device weight, as a string. The string is parsed as a * series of /path/to/device,weight elements, separated by ','. + * + * Since: v0.9.8 + * */ # define VIR_DOMAIN_BLKIO_DEVICE_WEIGHT "device_weight" @@ -1518,6 +1668,9 @@ char * virDomainGetSchedulerType(virDomainPtr domain, * the number of reading the block device per second, as a string. The * string is parsed as a series of /path/to/device, read_iops elements, * separated by ','. + * + * Since: v1.2.2 + * */ # define VIR_DOMAIN_BLKIO_DEVICE_READ_IOPS "device_read_iops_sec" @@ -1530,6 +1683,9 @@ char * virDomainGetSchedulerType(virDomainPtr domain, * the number of writing the block device per second, as a string. The * string is parsed as a series of /path/to/device, write_iops elements, * separated by ','. + * + * Since: v1.2.2 + * */ # define VIR_DOMAIN_BLKIO_DEVICE_WRITE_IOPS "device_write_iops_sec" @@ -1541,6 +1697,9 @@ char * virDomainGetSchedulerType(virDomainPtr domain, * the bytes of reading the block device per second, as a string. The * string is parsed as a series of /path/to/device, read_bps elements, * separated by ','. + * + * Since: v1.2.2 + * */ # define VIR_DOMAIN_BLKIO_DEVICE_READ_BPS "device_read_bytes_sec" @@ -1552,6 +1711,9 @@ char * virDomainGetSchedulerType(virDomainPtr domain, * the number of reading the block device per second, as a string. The * string is parsed as a series of /path/to/device, write_bps elements, * separated by ','. + * + * Since: v1.2.2 + * */ # define VIR_DOMAIN_BLKIO_DEVICE_WRITE_BPS "device_write_bytes_sec" @@ -1570,6 +1732,9 @@ int virDomainGetBlkioParameters(virDomainPtr domain, * VIR_DOMAIN_MEMORY_PARAM_UNLIMITED: * * Macro providing the virMemoryParameter value that indicates "unlimited" + * + * Since: v0.8.8 + * */ # define VIR_DOMAIN_MEMORY_PARAM_UNLIMITED 9007199254740991LL /* = INT64_MAX >> 10 */ @@ -1579,6 +1744,9 @@ int virDomainGetBlkioParameters(virDomainPtr domain, * * Macro for the memory tunable hard_limit: it represents the maximum memory * the guest can use, as a ullong. + * + * Since: v0.8.5 + * */ # define VIR_DOMAIN_MEMORY_HARD_LIMIT "hard_limit" @@ -1588,6 +1756,9 @@ int virDomainGetBlkioParameters(virDomainPtr domain, * * Macro for the memory tunable soft_limit: it represents the memory upper * limit enforced during memory contention, as a ullong. + * + * Since: v0.8.5 + * */ # define VIR_DOMAIN_MEMORY_SOFT_LIMIT "soft_limit" @@ -1597,6 +1768,9 @@ int virDomainGetBlkioParameters(virDomainPtr domain, * * Macro for the memory tunable min_guarantee: it represents the minimum * memory guaranteed to be reserved for the guest, as a ullong. + * + * Since: v0.8.5 + * */ # define VIR_DOMAIN_MEMORY_MIN_GUARANTEE "min_guarantee" @@ -1607,6 +1781,9 @@ int virDomainGetBlkioParameters(virDomainPtr domain, * Macro for the swap tunable swap_hard_limit: it represents the maximum swap * plus memory the guest can use, as a ullong. This limit has to be more than * VIR_DOMAIN_MEMORY_HARD_LIMIT. + * + * Since: v0.8.5 + * */ # define VIR_DOMAIN_MEMORY_SWAP_HARD_LIMIT "swap_hard_limit" @@ -1654,6 +1831,9 @@ typedef enum { * * Macro for typed parameter name that lists the numa nodeset of a * domain, as a string. + * + * Since: v0.9.9 + * */ # define VIR_DOMAIN_NUMA_NODESET "numa_nodeset" @@ -1662,6 +1842,9 @@ typedef enum { * * Macro for typed parameter name that lists the numa mode of a domain, * as an int containing a virDomainNumatuneMemMode value. + * + * Since: v0.9.9 + * */ # define VIR_DOMAIN_NUMA_MODE "numa_mode" @@ -1784,6 +1967,9 @@ int virDomainInterfaceStats (virDomainPtr dom, * VIR_DOMAIN_BANDWIDTH_IN_AVERAGE: * * Macro represents the inbound average of NIC bandwidth, as a uint. + * + * Since: v0.9.9 + * */ # define VIR_DOMAIN_BANDWIDTH_IN_AVERAGE "inbound.average" @@ -1791,6 +1977,9 @@ int virDomainInterfaceStats (virDomainPtr dom, * VIR_DOMAIN_BANDWIDTH_IN_PEAK: * * Macro represents the inbound peak of NIC bandwidth, as a uint. + * + * Since: v0.9.9 + * */ # define VIR_DOMAIN_BANDWIDTH_IN_PEAK "inbound.peak" @@ -1798,6 +1987,9 @@ int virDomainInterfaceStats (virDomainPtr dom, * VIR_DOMAIN_BANDWIDTH_IN_BURST: * * Macro represents the inbound burst of NIC bandwidth, as a uint. + * + * Since: v0.9.9 + * */ # define VIR_DOMAIN_BANDWIDTH_IN_BURST "inbound.burst" @@ -1805,6 +1997,9 @@ int virDomainInterfaceStats (virDomainPtr dom, * VIR_DOMAIN_BANDWIDTH_IN_FLOOR: * * Macro represents the inbound floor of NIC bandwidth, as a uint. + * + * Since: v1.2.19 + * */ # define VIR_DOMAIN_BANDWIDTH_IN_FLOOR "inbound.floor" @@ -1812,6 +2007,9 @@ int virDomainInterfaceStats (virDomainPtr dom, * VIR_DOMAIN_BANDWIDTH_OUT_AVERAGE: * * Macro represents the outbound average of NIC bandwidth, as a uint. + * + * Since: v0.9.9 + * */ # define VIR_DOMAIN_BANDWIDTH_OUT_AVERAGE "outbound.average" @@ -1819,6 +2017,9 @@ int virDomainInterfaceStats (virDomainPtr dom, * VIR_DOMAIN_BANDWIDTH_OUT_PEAK: * * Macro represents the outbound peak of NIC bandwidth, as a uint. + * + * Since: v0.9.9 + * */ # define VIR_DOMAIN_BANDWIDTH_OUT_PEAK "outbound.peak" @@ -1826,6 +2027,9 @@ int virDomainInterfaceStats (virDomainPtr dom, * VIR_DOMAIN_BANDWIDTH_OUT_BURST: * * Macro represents the outbound burst of NIC bandwidth, as a uint. + * + * Since: v0.9.9 + * */ # define VIR_DOMAIN_BANDWIDTH_OUT_BURST "outbound.burst" @@ -2131,6 +2335,9 @@ int virDomainDelIOThread(virDomainPtr domain, * will cause more CPU time to be allocated the guest. A value set too * small will not provide enough cycles for the guest to process data. * The polling interval is not available for statistical purposes. + * + * Since: v4.10.0 + * */ # define VIR_DOMAIN_IOTHREAD_POLL_MAX_NS "poll_max_ns" @@ -2141,6 +2348,9 @@ int virDomainDelIOThread(virDomainPtr domain, * use to grow its polling interval up to the poll_max_ns value. A value * of 0 (zero) allows the hypervisor to choose its own value. The algorithm * to use for adjustment is hypervisor specific. + * + * Since: v4.10.0 + * */ # define VIR_DOMAIN_IOTHREAD_POLL_GROW "poll_grow" @@ -2152,6 +2362,9 @@ int virDomainDelIOThread(virDomainPtr domain, * the poll_max_ns value. A value of 0 (zero) allows the hypervisor to * choose its own value. The algorithm to use for adjustment is hypervisor * specific. + * + * Since: v4.10.0 + * */ # define VIR_DOMAIN_IOTHREAD_POLL_SHRINK "poll_shrink" @@ -2169,6 +2382,9 @@ int virDomainSetIOThreadParams(virDomainPtr domain, * * This macro is to be used in conjunction with virDomainPinVcpu() API. * It sets the bit (CPU usable) of the related cpu in cpumap. + * + * Since: v0.1.4 + * */ # define VIR_USE_CPU(cpumap, cpu) ((cpumap)[(cpu) / 8] |= (1 << ((cpu) % 8))) @@ -2180,6 +2396,9 @@ int virDomainSetIOThreadParams(virDomainPtr domain, * * This macro is to be used in conjunction with virDomainPinVcpu() API. * It resets the bit (CPU not usable) of the related cpu in cpumap. + * + * Since: v0.1.4 + * */ # define VIR_UNUSE_CPU(cpumap, cpu) ((cpumap)[(cpu) / 8] &= ~(1 << ((cpu) % 8))) @@ -2191,6 +2410,9 @@ int virDomainSetIOThreadParams(virDomainPtr domain, * * This macro can be used in conjunction with virNodeGetCPUMap() API. * It returns non-zero if the bit of the related CPU is set. + * + * Since: v1.0.0 + * */ # define VIR_CPU_USED(cpumap, cpu) ((cpumap)[(cpu) / 8] & (1 << ((cpu) % 8))) @@ -2202,6 +2424,9 @@ int virDomainSetIOThreadParams(virDomainPtr domain, * This macro is to be used in conjunction with virDomainPinVcpu() API. * It returns the length (in bytes) required to store the complete * CPU map between a single virtual & all physical CPUs of a domain. + * + * Since: v0.1.4 + * */ # define VIR_CPU_MAPLEN(cpu) (((cpu) + 7) / 8) @@ -2223,6 +2448,9 @@ int virDomainGetVcpus (virDomainPtr domain, * This macro is to be used in conjunction with virDomainGetVcpus() API. * VIR_CPU_USABLE macro returns a non-zero value (true) if the cpu * is usable by the vcpu, and 0 otherwise. + * + * Since: v0.1.4 + * */ # define VIR_CPU_USABLE(cpumaps, maplen, vcpu, cpu) \ @@ -2241,6 +2469,9 @@ int virDomainGetVcpus (virDomainPtr domain, * virDomainPinVcpu() APIs. VIR_COPY_CPUMAP macro extracts the cpumap of * the specified vcpu from cpumaps array and copies it into cpumap to be used * later by virDomainPinVcpu() API. + * + * Since: v0.1.4 + * */ # define VIR_COPY_CPUMAP(cpumaps, maplen, vcpu, cpumap) \ memcpy(cpumap, VIR_GET_CPUMAP(cpumaps, maplen, vcpu), maplen) @@ -2255,6 +2486,9 @@ int virDomainGetVcpus (virDomainPtr domain, * This macro is to be used in conjunction with virDomainGetVcpus() and * virDomainPinVcpu() APIs. VIR_GET_CPUMAP macro returns a pointer to the * cpumap of the specified vcpu from cpumaps array. + * + * Since: v0.1.4 + * */ # define VIR_GET_CPUMAP(cpumaps, maplen, vcpu) (&((cpumaps)[(vcpu) * (maplen)])) @@ -2345,6 +2579,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * which can be used to measure the usage of cache (bytes) by * applications running on the platform. It corresponds to the * "perf.cmt" field in the *Stats APIs. + * + * Since: v1.3.3 + * */ # define VIR_PERF_PARAM_CMT "cmt" @@ -2355,6 +2592,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * which can be used to monitor total system bandwidth (bytes/s) * from one level of cache to another. It corresponds to the * "perf.mbmt" field in the *Stats APIs. + * + * Since: v1.3.5 + * */ # define VIR_PERF_PARAM_MBMT "mbmt" @@ -2366,6 +2606,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * which can be used to monitor the amount of data (bytes/s) sent * through the memory controller on the socket. It corresponds to * the "perf.mbml" field in the *Stats APIs. + * + * Since: v1.3.5 + * */ # define VIR_PERF_PARAM_MBML "mbml" @@ -2376,6 +2619,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * event which can be used to measure the count of cache misses by * applications running on the platform. It corresponds to the * "perf.cache_misses" field in the *Stats APIs. + * + * Since: v2.3.0 + * */ # define VIR_PERF_PARAM_CACHE_MISSES "cache_misses" @@ -2386,6 +2632,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of cache hits * by applications running on the platform. It corresponds to the * "perf.cache_references" field in the *Stats APIs. + * + * Since: v2.3.0 + * */ # define VIR_PERF_PARAM_CACHE_REFERENCES "cache_references" @@ -2396,6 +2645,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * event which can be used to measure the count of instructions * by applications running on the platform. It corresponds to the * "perf.instructions" field in the *Stats APIs. + * + * Since: v2.3.0 + * */ # define VIR_PERF_PARAM_INSTRUCTIONS "instructions" @@ -2406,6 +2658,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * describing the total/elapsed cpu cycles. This can be used to measure * how many cpu cycles one instruction needs. * It corresponds to the "perf.cpu_cycles" field in the *Stats APIs. + * + * Since: v2.3.0 + * */ # define VIR_PERF_PARAM_CPU_CYCLES "cpu_cycles" @@ -2416,6 +2671,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of branch instructions * by applications running on the platform. It corresponds to the * "perf.branch_instructions" field in the *Stats APIs. + * + * Since: v3.0.0 + * */ # define VIR_PERF_PARAM_BRANCH_INSTRUCTIONS "branch_instructions" @@ -2426,6 +2684,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of branch misses * by applications running on the platform. It corresponds to the * "perf.branch_misses" field in the *Stats APIs. + * + * Since: v3.0.0 + * */ # define VIR_PERF_PARAM_BRANCH_MISSES "branch_misses" @@ -2436,6 +2697,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of bus cycles * by applications running on the platform. It corresponds to the * "perf.bus_cycles" field in the *Stats APIs. + * + * Since: v3.0.0 + * */ # define VIR_PERF_PARAM_BUS_CYCLES "bus_cycles" @@ -2447,6 +2711,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * in the frontend of the instruction processor pipeline by applications * running on the platform. It corresponds to the * "perf.stalled_cycles_frontend" field in the *Stats APIs. + * + * Since: v3.0.0 + * */ # define VIR_PERF_PARAM_STALLED_CYCLES_FRONTEND "stalled_cycles_frontend" @@ -2458,6 +2725,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * in the backend of the instruction processor pipeline by application * running on the platform. It corresponds to the * "perf.stalled_cycles_backend" field in the *Stats APIs. + * + * Since: v3.0.0 + * */ # define VIR_PERF_PARAM_STALLED_CYCLES_BACKEND "stalled_cycles_backend" @@ -2469,6 +2739,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * cycles not affected by CPU frequency scaling by applications * running on the platform. It corresponds to the * "perf.ref_cpu_cycles" field in the *Stats APIs. + * + * Since: v3.0.0 + * */ # define VIR_PERF_PARAM_REF_CPU_CYCLES "ref_cpu_cycles" @@ -2480,6 +2753,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * clock time by applications running on the platform. It * corresponds to the "perf.cpu_clock" field in the *Stats * APIs. + * + * Since: v3.2.0 + * */ # define VIR_PERF_PARAM_CPU_CLOCK "cpu_clock" @@ -2491,6 +2767,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * clock time by applications running on the platform. It * corresponds to the "perf.task_clock" field in the *Stats * APIs. + * + * Since: v3.2.0 + * */ # define VIR_PERF_PARAM_TASK_CLOCK "task_clock" @@ -2501,6 +2780,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of page * faults by applications running on the platform. It corresponds * to the "perf.page_faults" field in the *Stats APIs. +* +* Since: v3.2.0 +* */ # define VIR_PERF_PARAM_PAGE_FAULTS "page_faults" @@ -2511,6 +2793,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of context * switches by applications running on the platform. It corresponds * to the "perf.context_switches" field in the *Stats APIs. + * + * Since: v3.2.0 + * */ # define VIR_PERF_PARAM_CONTEXT_SWITCHES "context_switches" @@ -2521,6 +2806,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of cpu * migrations by applications running on the platform. It corresponds * to the "perf.cpu_migrations" field in the *Stats APIs. + * + * Since: v3.2.0 + * */ # define VIR_PERF_PARAM_CPU_MIGRATIONS "cpu_migrations" @@ -2531,6 +2819,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of minor page * faults by applications running on the platform. It corresponds * to the "perf.page_faults_min" field in the *Stats APIs. + * + * Since: v3.2.0 + * */ # define VIR_PERF_PARAM_PAGE_FAULTS_MIN "page_faults_min" @@ -2541,6 +2832,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of major page * faults by applications running on the platform. It corresponds * to the "perf.page_faults_maj" field in the *Stats APIs. + * + * Since: v3.2.0 + * */ # define VIR_PERF_PARAM_PAGE_FAULTS_MAJ "page_faults_maj" @@ -2551,6 +2845,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of alignment * faults by applications running on the platform. It corresponds * to the "perf.alignment_faults" field in the *Stats APIs. + * + * Since: v3.2.0 + * */ # define VIR_PERF_PARAM_ALIGNMENT_FAULTS "alignment_faults" @@ -2561,6 +2858,9 @@ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats); * perf event which can be used to measure the count of emulation * faults by applications running on the platform. It corresponds * to the "perf.emulation_faults" field in the *Stats APIs. + * + * Since: v3.2.0 + * */ # define VIR_PERF_PARAM_EMULATION_FAULTS "emulation_faults" @@ -2752,6 +3052,9 @@ typedef enum { * allowing a subsequent change of bandwidth via * virDomainBlockJobSetSpeed(). The actual speed can be determined * with virDomainGetBlockJobInfo(). + * + * Since: v1.2.8 + * */ # define VIR_DOMAIN_BLOCK_COPY_BANDWIDTH "bandwidth" @@ -2763,6 +3066,9 @@ typedef enum { * restrict this to be a power of two or fall within a certain * range. Specifying 0 is the same as omitting this parameter, to * request the hypervisor default. + * + * Since: v1.2.8 + * */ # define VIR_DOMAIN_BLOCK_COPY_GRANULARITY "granularity" @@ -2772,6 +3078,9 @@ typedef enum { * how much data in bytes can be in flight between source and destination, * as an unsigned long long. Specifying 0 is the same as omitting this * parameter, to request the hypervisor default. + * + * Since: v1.2.8 + * */ # define VIR_DOMAIN_BLOCK_COPY_BUF_SIZE "buf-size" @@ -2813,6 +3122,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the total * bytes per second permitted through a block device, as a ullong. + * + * Since: v0.9.8 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_BYTES_SEC "total_bytes_sec" @@ -2821,6 +3133,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the read * bytes per second permitted through a block device, as a ullong. + * + * Since: v0.9.8 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_READ_BYTES_SEC "read_bytes_sec" @@ -2829,6 +3144,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the write * bytes per second permitted through a block device, as a ullong. + * + * Since: v0.9.8 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_WRITE_BYTES_SEC "write_bytes_sec" @@ -2837,6 +3155,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the total * I/O operations per second permitted through a block device, as a ullong. + * + * Since: v0.9.8 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_IOPS_SEC "total_iops_sec" @@ -2845,6 +3166,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the read * I/O operations per second permitted through a block device, as a ullong. + * + * Since: v0.9.8 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_READ_IOPS_SEC "read_iops_sec" @@ -2852,6 +3176,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * VIR_DOMAIN_BLOCK_IOTUNE_WRITE_IOPS_SEC: * Macro for the BlockIoTune tunable weight: it represents the write * I/O operations per second permitted through a block device, as a ullong. + * + * Since: v0.9.8 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_WRITE_IOPS_SEC "write_iops_sec" @@ -2860,6 +3187,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the maximum total * bytes per second permitted through a block device, as a ullong. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX "total_bytes_sec_max" @@ -2868,6 +3198,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the maximum read * bytes per second permitted through a block device, as a ullong. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_READ_BYTES_SEC_MAX "read_bytes_sec_max" @@ -2876,6 +3209,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the maximum write * bytes per second permitted through a block device, as a ullong. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX "write_bytes_sec_max" @@ -2884,6 +3220,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the maximum * I/O operations per second permitted through a block device, as a ullong. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX "total_iops_sec_max" @@ -2892,6 +3231,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the maximum read * I/O operations per second permitted through a block device, as a ullong. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_READ_IOPS_SEC_MAX "read_iops_sec_max" @@ -2899,6 +3241,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * VIR_DOMAIN_BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX: * Macro for the BlockIoTune tunable weight: it represents the maximum write * I/O operations per second permitted through a block device, as a ullong. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX "write_iops_sec_max" @@ -2907,6 +3252,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the duration in * seconds for the burst allowed by total_bytes_sec_max, as a ullong. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_BYTES_SEC_MAX_LENGTH "total_bytes_sec_max_length" @@ -2915,6 +3263,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the duration in * seconds for the burst allowed by read_bytes_sec_max, as a ullong. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_READ_BYTES_SEC_MAX_LENGTH "read_bytes_sec_max_length" @@ -2923,6 +3274,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the duration in * seconds for the burst allowed by write_bytes_sec_max, as a ullong. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_WRITE_BYTES_SEC_MAX_LENGTH "write_bytes_sec_max_length" @@ -2931,6 +3285,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the duration in * seconds for the burst allowed by total_iops_sec_max, as a ullong. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_TOTAL_IOPS_SEC_MAX_LENGTH "total_iops_sec_max_length" @@ -2939,6 +3296,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the duration in * seconds for the burst allowed by read_iops_sec_max, as a ullong. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_READ_IOPS_SEC_MAX_LENGTH "read_iops_sec_max_length" @@ -2947,6 +3307,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * * Macro for the BlockIoTune tunable weight: it represents the duration in * seconds for the burst allowed by write_iops_sec_max, as a ullong. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_WRITE_IOPS_SEC_MAX_LENGTH "write_iops_sec_max_length" @@ -2954,6 +3317,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * VIR_DOMAIN_BLOCK_IOTUNE_SIZE_IOPS_SEC: * Macro for the BlockIoTune tunable weight: it represents the size * I/O operations per second permitted through a block device, as a ullong. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_SIZE_IOPS_SEC "size_iops_sec" @@ -2961,6 +3327,9 @@ int virDomainBlockCommit(virDomainPtr dom, const char *disk, const char *base, * VIR_DOMAIN_BLOCK_IOTUNE_GROUP_NAME: * Macro for the BlockIoTune tunable weight: it represents a group name to * allow sharing of I/O throttling quota between multiple drives, as a string. + * + * Since: v3.0.0 + * */ # define VIR_DOMAIN_BLOCK_IOTUNE_GROUP_NAME "group_name" @@ -3044,6 +3413,9 @@ typedef enum { * VIR_KEYCODE_SET_RFB: * * Compatibility alias for VIR_KEYCODE_SET_QNUM, which replaced it since 4.2.0. + * + * Since: v0.9.5 + * */ # define VIR_KEYCODE_SET_RFB VIR_KEYCODE_SET_QNUM @@ -3051,6 +3423,9 @@ typedef enum { * VIR_DOMAIN_SEND_KEY_MAX_KEYS: * * Maximum number of keycodes that can be sent in one virDomainSendKey() call. + * + * Since: v0.9.3 + * */ # define VIR_DOMAIN_SEND_KEY_MAX_KEYS 16 @@ -3543,6 +3918,9 @@ typedef enum { * virDomainGetJobStats field: the operation which started the job as * VIR_TYPED_PARAM_INT. The values correspond to the items in * virDomainJobOperation enum. + * + * Since: v3.3.0 + * */ # define VIR_DOMAIN_JOB_OPERATION "operation" @@ -3553,6 +3931,9 @@ typedef enum { * job, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to timeElapsed field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_TIME_ELAPSED "time_elapsed" @@ -3563,6 +3944,9 @@ typedef enum { * migration job NOT including the time required to transfer control * flow from the source host to the destination host, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.15 + * */ # define VIR_DOMAIN_JOB_TIME_ELAPSED_NET "time_elapsed_net" @@ -3573,6 +3957,9 @@ typedef enum { * jobs, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to timeRemaining field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_TIME_REMAINING "time_remaining" @@ -3583,6 +3970,9 @@ typedef enum { * during migration, as VIR_TYPED_PARAM_ULLONG. The real computed downtime * between the time guest CPUs were paused and the time they were resumed * is reported for completed migration. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_DOWNTIME "downtime" @@ -3592,6 +3982,9 @@ typedef enum { * virDomainGetJobStats field: real measured downtime (ms) NOT including * the time required to transfer control flow from the source host to the * destination host, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.15 + * */ # define VIR_DOMAIN_JOB_DOWNTIME_NET "downtime_net" @@ -3601,6 +3994,9 @@ typedef enum { * virDomainGetJobStats field: total time in milliseconds spent preparing * the migration in the 'setup' phase before the iterations begin, as * VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_JOB_SETUP_TIME "setup_time" @@ -3616,6 +4012,9 @@ typedef enum { * VIR_DOMAIN_JOB_DATA_PROCESSED + VIR_DOMAIN_JOB_DATA_REMAINING. * * This field corresponds to dataTotal field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_DATA_TOTAL "data_total" @@ -3626,6 +4025,9 @@ typedef enum { * beginning of the job, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to dataProcessed field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_DATA_PROCESSED "data_processed" @@ -3636,6 +4038,9 @@ typedef enum { * transferred, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to dataRemaining field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_DATA_REMAINING "data_remaining" @@ -3646,6 +4051,9 @@ typedef enum { * tracking guest memory progress, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to memTotal field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_MEMORY_TOTAL "memory_total" @@ -3656,6 +4064,9 @@ typedef enum { * tracking guest memory progress, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to memProcessed field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_MEMORY_PROCESSED "memory_processed" @@ -3666,6 +4077,9 @@ typedef enum { * tracking guest memory progress, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to memRemaining field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_MEMORY_REMAINING "memory_remaining" @@ -3678,6 +4092,9 @@ typedef enum { * * The most common example of such pages are zero pages, i.e., pages filled * with zero bytes. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_MEMORY_CONSTANT "memory_constant" @@ -3688,6 +4105,9 @@ typedef enum { * any kind of compression (i.e., pages which were not filled with a constant * byte and which could not be compressed) transferred since the beginning * of the migration job, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_MEMORY_NORMAL "memory_normal" @@ -3698,6 +4118,9 @@ typedef enum { * as VIR_TYPED_PARAM_ULLONG. * * See VIR_DOMAIN_JOB_MEMORY_NORMAL for more details. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_MEMORY_NORMAL_BYTES "memory_normal_bytes" @@ -3706,6 +4129,9 @@ typedef enum { * * virDomainGetJobStats field: network throughput used while migrating * memory in Bytes per second, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_JOB_MEMORY_BPS "memory_bps" @@ -3714,6 +4140,9 @@ typedef enum { * virDomainGetJobStats field: number of memory pages dirtied by the guest * per second, as VIR_TYPED_PARAM_ULLONG. This statistics makes sense only * when live migration is running. + * + * Since: v1.3.1 + * */ # define VIR_DOMAIN_JOB_MEMORY_DIRTY_RATE "memory_dirty_rate" @@ -3725,6 +4154,9 @@ typedef enum { * convert other page based statistics, such as * VIR_DOMAIN_JOB_MEMORY_DIRTY_RATE or VIR_DOMAIN_JOB_COMPRESSION_PAGES * to bytes. + * + * Since: v3.9.0 + * */ # define VIR_DOMAIN_JOB_MEMORY_PAGE_SIZE "memory_page_size" @@ -3736,6 +4168,9 @@ typedef enum { * when memory starts to be transferred and the value is increased by one * every time a new iteration is started to transfer memory pages dirtied * since the last iteration. + * + * Since: v1.3.1 + * */ # define VIR_DOMAIN_JOB_MEMORY_ITERATION "memory_iteration" @@ -3746,6 +4181,9 @@ typedef enum { * destination host during post-copy migration, as VIR_TYPED_PARAM_ULLONG. * This counter is incremented whenever the migrated domain tries to access * a memory page which has not been transferred from the source host yet. + * + * Since: v5.0.0 + * */ # define VIR_DOMAIN_JOB_MEMORY_POSTCOPY_REQS "memory_postcopy_requests" @@ -3756,6 +4194,9 @@ typedef enum { * tracking guest disk progress, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to fileTotal field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_DISK_TOTAL "disk_total" @@ -3766,6 +4207,9 @@ typedef enum { * tracking guest disk progress, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to fileProcessed field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_DISK_PROCESSED "disk_processed" @@ -3776,6 +4220,9 @@ typedef enum { * tracking guest disk progress, as VIR_TYPED_PARAM_ULLONG. * * This field corresponds to fileRemaining field in virDomainJobInfo. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_DISK_REMAINING "disk_remaining" @@ -3784,6 +4231,9 @@ typedef enum { * * virDomainGetJobStats field: network throughput used while migrating * disks in Bytes per second, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_JOB_DISK_BPS "disk_bps" @@ -3793,6 +4243,9 @@ typedef enum { * virDomainGetJobStats field: size of the cache (in bytes) used for * compressing repeatedly transferred memory pages during live migration, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_COMPRESSION_CACHE "compression_cache" @@ -3801,6 +4254,9 @@ typedef enum { * * virDomainGetJobStats field: number of compressed bytes transferred * since the beginning of migration, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_COMPRESSION_BYTES "compression_bytes" @@ -3809,6 +4265,9 @@ typedef enum { * * virDomainGetJobStats field: number of compressed pages transferred * since the beginning of migration, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_COMPRESSION_PAGES "compression_pages" @@ -3818,6 +4277,9 @@ typedef enum { * virDomainGetJobStats field: number of repeatedly changing pages that * were not found in compression cache and thus could not be compressed, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_COMPRESSION_CACHE_MISSES "compression_cache_misses" @@ -3828,6 +4290,9 @@ typedef enum { * were found in compression cache but were sent uncompressed because * the result of compression was larger than the original page as a whole, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.0.3 + * */ # define VIR_DOMAIN_JOB_COMPRESSION_OVERFLOW "compression_overflow" @@ -3837,6 +4302,9 @@ typedef enum { * virDomainGetJobStats field: current percentage guest CPUs are throttled * to when auto-convergence decided migration was not converging, as * VIR_TYPED_PARAM_INT. + * + * Since: v2.0.0 + * */ # define VIR_DOMAIN_JOB_AUTO_CONVERGE_THROTTLE "auto_converge_throttle" @@ -3845,6 +4313,9 @@ typedef enum { * * virDomainGetJobStats field: Present only in statistics for a completed job. * Successful completion of the job as VIR_TYPED_PARAM_BOOLEAN. + * + * Since: v6.0.0 + * */ # define VIR_DOMAIN_JOB_SUCCESS "success" @@ -3853,6 +4324,9 @@ typedef enum { * * virDomainGetJobStats field: Present only in statistics for a completed job. * Optional error message for a failed job. + * + * Since: v6.3.0 + * */ # define VIR_DOMAIN_JOB_ERRMSG "errmsg" @@ -3861,6 +4335,9 @@ typedef enum { * VIR_DOMAIN_JOB_DISK_TEMP_USED: * virDomainGetJobStats field: current usage of temporary disk space for the * job in bytes as VIR_TYPED_PARAM_ULLONG. + * + * Since: v6.0.0 + * */ # define VIR_DOMAIN_JOB_DISK_TEMP_USED "disk_temp_used" @@ -3868,6 +4345,9 @@ typedef enum { * VIR_DOMAIN_JOB_DISK_TEMP_TOTAL: * virDomainGetJobStats field: possible total temporary disk space for the * job in bytes as VIR_TYPED_PARAM_ULLONG. + * + * Since: v6.0.0 + * */ # define VIR_DOMAIN_JOB_DISK_TEMP_TOTAL "disk_temp_total" @@ -4429,6 +4909,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents formatted pinning for one vcpu specified by id which is * appended to the parameter name, for example "cputune.vcpupin1", * as VIR_TYPED_PARAM_STRING. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_CPU_VCPUPIN "cputune.vcpupin%u" @@ -4437,6 +4920,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents formatted pinning for emulator process, * as VIR_TYPED_PARAM_STRING. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_CPU_EMULATORPIN "cputune.emulatorpin" @@ -4446,6 +4932,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents formatted pinning for one IOThread specified by id which is * appended to the parameter name, for example "cputune.iothreadpin1", * as VIR_TYPED_PARAM_STRING. + * + * Since: v1.2.14 + * */ # define VIR_DOMAIN_TUNABLE_CPU_IOTHREADSPIN "cputune.iothreadpin%u" @@ -4454,6 +4943,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents proportional weight of the scheduler used on the * host cpu, when using the posix scheduler, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_CPU_CPU_SHARES "cputune.cpu_shares" @@ -4462,6 +4954,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the enforcement period for a quota, in microseconds, * for whole domain, when using the posix scheduler, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.3.3 + * */ # define VIR_DOMAIN_TUNABLE_CPU_GLOBAL_PERIOD "cputune.global_period" @@ -4470,6 +4965,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the maximum bandwidth to be used within a period for * whole domain, when using the posix scheduler, as VIR_TYPED_PARAM_LLONG. + * + * Since: v1.3.3 + * */ # define VIR_DOMAIN_TUNABLE_CPU_GLOBAL_QUOTA "cputune.global_quota" @@ -4478,6 +4976,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the enforcement period for a quota, in microseconds, * for vcpus only, when using the posix scheduler, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_CPU_VCPU_PERIOD "cputune.vcpu_period" @@ -4486,6 +4987,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the maximum bandwidth to be used within a period for * vcpus only, when using the posix scheduler, as VIR_TYPED_PARAM_LLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_CPU_VCPU_QUOTA "cputune.vcpu_quota" @@ -4495,6 +4999,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents the enforcement period for a quota in microseconds, * when using the posix scheduler, for all emulator activity not tied to * vcpus, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_CPU_EMULATOR_PERIOD "cputune.emulator_period" @@ -4504,6 +5011,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents the maximum bandwidth to be used within a period for * all emulator activity not tied to vcpus, when using the posix scheduler, * as an VIR_TYPED_PARAM_LLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_CPU_EMULATOR_QUOTA "cputune.emulator_quota" @@ -4512,6 +5022,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the enforcement period for a quota, in microseconds, for * iothreads only, when using the posix scheduler, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v2.2.0 + * */ # define VIR_DOMAIN_TUNABLE_CPU_IOTHREAD_PERIOD "cputune.iothread_period" @@ -4520,6 +5033,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the maximum bandwidth to be used within a period for * iothreads only, when using the posix scheduler, as VIR_TYPED_PARAM_LLONG. + * + * Since: v2.2.0 + * */ # define VIR_DOMAIN_TUNABLE_CPU_IOTHREAD_QUOTA "cputune.iothread_quota" @@ -4528,6 +5044,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the name of guest disk for which the values are updated, * as VIR_TYPED_PARAM_STRING. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_DISK "blkdeviotune.disk" @@ -4536,6 +5055,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the total throughput limit in bytes per second, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_TOTAL_BYTES_SEC "blkdeviotune.total_bytes_sec" @@ -4544,6 +5066,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the read throughput limit in bytes per second, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_READ_BYTES_SEC "blkdeviotune.read_bytes_sec" @@ -4552,6 +5077,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the write throughput limit in bytes per second, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_WRITE_BYTES_SEC "blkdeviotune.write_bytes_sec" @@ -4560,6 +5088,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the total I/O operations per second, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_TOTAL_IOPS_SEC "blkdeviotune.total_iops_sec" @@ -4568,6 +5099,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the read I/O operations per second, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_READ_IOPS_SEC "blkdeviotune.read_iops_sec" @@ -4576,6 +5110,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the write I/O operations per second, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.9 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_WRITE_IOPS_SEC "blkdeviotune.write_iops_sec" @@ -4584,6 +5121,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the total throughput limit during bursts in * maximum bytes per second, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX "blkdeviotune.total_bytes_sec_max" @@ -4592,6 +5132,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the read throughput limit during bursts in * maximum bytes per second, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_READ_BYTES_SEC_MAX "blkdeviotune.read_bytes_sec_max" @@ -4600,6 +5143,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the write throughput limit during bursts in * maximum bytes per second, as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX "blkdeviotune.write_bytes_sec_max" @@ -4608,6 +5154,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the total maximum I/O operations per second during bursts, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX "blkdeviotune.total_iops_sec_max" @@ -4616,6 +5165,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the read maximum I/O operations per second during bursts, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_READ_IOPS_SEC_MAX "blkdeviotune.read_iops_sec_max" @@ -4624,6 +5176,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the write maximum I/O operations per second during bursts, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX "blkdeviotune.write_iops_sec_max" @@ -4632,6 +5187,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the size maximum I/O operations per second, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v1.2.11 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_SIZE_IOPS_SEC "blkdeviotune.size_iops_sec" @@ -4640,6 +5198,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * Macro represents the group name to be used, * as VIR_TYPED_PARAM_STRING. + * + * Since: v3.0.0 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_GROUP_NAME "blkdeviotune.group_name" @@ -4649,6 +5210,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents the length in seconds allowed for a burst period * for the blkdeviotune.total_bytes_sec_max, * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_TOTAL_BYTES_SEC_MAX_LENGTH "blkdeviotune.total_bytes_sec_max_length" @@ -4658,6 +5222,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents the length in seconds allowed for a burst period * for the blkdeviotune.read_bytes_sec_max * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_READ_BYTES_SEC_MAX_LENGTH "blkdeviotune.read_bytes_sec_max_length" @@ -4667,6 +5234,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents the length in seconds allowed for a burst period * for the blkdeviotune.write_bytes_sec_max * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_WRITE_BYTES_SEC_MAX_LENGTH "blkdeviotune.write_bytes_sec_max_length" @@ -4676,6 +5246,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents the length in seconds allowed for a burst period * for the blkdeviotune.total_iops_sec_max * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_TOTAL_IOPS_SEC_MAX_LENGTH "blkdeviotune.total_iops_sec_max_length" @@ -4685,6 +5258,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents the length in seconds allowed for a burst period * for the blkdeviotune.read_iops_sec_max * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_READ_IOPS_SEC_MAX_LENGTH "blkdeviotune.read_iops_sec_max_length" @@ -4694,6 +5270,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * Macro represents the length in seconds allowed for a burst period * for the blkdeviotune.write_iops_sec_max * as VIR_TYPED_PARAM_ULLONG. + * + * Since: v2.4.0 + * */ # define VIR_DOMAIN_TUNABLE_BLKDEV_WRITE_IOPS_SEC_MAX_LENGTH "blkdeviotune.write_iops_sec_max_length" @@ -4846,6 +5425,9 @@ typedef void (*virConnectDomainEventMemoryDeviceSizeChangeCallback)(virConnectPt * * Used to cast the event specific callback into the generic one * for use for virConnectDomainEventRegisterAny() + * + * Since: v0.8.0 + * */ # define VIR_DOMAIN_EVENT_CALLBACK(cb) ((virConnectDomainEventGenericCallback)(cb)) @@ -5033,18 +5615,31 @@ typedef enum { * * Macro providing the field length of virSchedParameter. Provided * for backwards compatibility; VIR_TYPED_PARAM_FIELD_LENGTH is the - * preferred value since 0.9.2. + * preferred value + * + * Since: v0.2.3 + * */ # define VIR_DOMAIN_SCHED_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH +/** + * _virSchedParameter: + * + * Since: v0.2.3 + * + */ +# define _virSchedParameter _virTypedParameter + /** * virSchedParameter: * * a virSchedParameter is the set of scheduler parameters. * Provided for backwards compatibility; virTypedParameter is the - * preferred alias since 0.9.2. + * preferred alias. + * + * Since: v0.9.2 + * */ -# define _virSchedParameter _virTypedParameter typedef struct _virTypedParameter virSchedParameter; /** @@ -5077,18 +5672,31 @@ typedef enum { * * Macro providing the field length of virBlkioParameter. Provided * for backwards compatibility; VIR_TYPED_PARAM_FIELD_LENGTH is the - * preferred value since 0.9.2. + * preferred value. + * + * Since: v0.9.0 + * */ # define VIR_DOMAIN_BLKIO_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH +/** + * _virBlkioParameter: + * + * Since: v0.9.0 + * + */ +# define _virBlkioParameter _virTypedParameter + /** * virBlkioParameter: * * a virBlkioParameter is the set of blkio parameters. * Provided for backwards compatibility; virTypedParameter is the - * preferred alias since 0.9.2. + * preferred alias. + * + * Since: v0.9.2 + * */ -# define _virBlkioParameter _virTypedParameter typedef struct _virTypedParameter virBlkioParameter; /** @@ -5121,18 +5729,31 @@ typedef enum { * * Macro providing the field length of virMemoryParameter. Provided * for backwards compatibility; VIR_TYPED_PARAM_FIELD_LENGTH is the - * preferred value since 0.9.2. + * preferred value. + * + * Since: v0.8.5 + * */ # define VIR_DOMAIN_MEMORY_FIELD_LENGTH VIR_TYPED_PARAM_FIELD_LENGTH +/** + * _virMemoryParameter: + * + * Since: v0.8.5 + * + */ +# define _virMemoryParameter _virTypedParameter + /** * virMemoryParameter: * * a virMemoryParameter is the set of scheduler parameters. * Provided for backwards compatibility; virTypedParameter is the - * preferred alias since 0.9.2. + * preferred alias. + * + * Since: v0.9.2 + * */ -# define _virMemoryParameter _virTypedParameter typedef struct _virTypedParameter virMemoryParameter; /** @@ -5248,6 +5869,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain, * * Macro represents the launch measurement of the SEV guest, * as VIR_TYPED_PARAM_STRING. + * + * Since: v4.5.0 + * */ # define VIR_DOMAIN_LAUNCH_SECURITY_SEV_MEASUREMENT "sev-measurement" @@ -5257,6 +5881,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain, * * Macro represents the API major version of the SEV host, * as VIR_TYPED_PARAM_UINT. + * + * Since: v8.0.0 + * */ # define VIR_DOMAIN_LAUNCH_SECURITY_SEV_API_MAJOR "sev-api-major" @@ -5265,6 +5892,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain, * * Macro represents the API minor version of the SEV guest, * as VIR_TYPED_PARAM_UINT. + * + * Since: v8.0.0 + * */ # define VIR_DOMAIN_LAUNCH_SECURITY_SEV_API_MINOR "sev-api-minor" @@ -5273,6 +5903,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain, * * Macro represents the build ID of the SEV host, * as VIR_TYPED_PARAM_UINT. + * + * Since: v8.0.0 + * */ # define VIR_DOMAIN_LAUNCH_SECURITY_SEV_BUILD_ID "sev-build-id" @@ -5281,6 +5914,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain, * * Macro represents the policy of the SEV guest, * as VIR_TYPED_PARAM_UINT. + * + * Since: v8.0.0 + * */ # define VIR_DOMAIN_LAUNCH_SECURITY_SEV_POLICY "sev-policy" @@ -5292,6 +5928,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain, * the SEV firmware to recover the plain text of the launch secret. See * section "6.6 LAUNCH_SECRET" in the SEV API specification for a detailed * description of the secret header. + * + * Since: v8.0.0 + * */ # define VIR_DOMAIN_LAUNCH_SECURITY_SEV_SECRET_HEADER "sev-secret-header" @@ -5302,6 +5941,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain, * base64-encoded VIR_TYPED_PARAM_STRING containing an encrypted launch * secret. The secret is created by the domain owner after the SEV launch * measurement is retrieved and verified. + * + * Since: v8.0.0 + * */ # define VIR_DOMAIN_LAUNCH_SECURITY_SEV_SECRET "sev-secret" @@ -5311,6 +5953,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain, * A macro used to represent the physical address within the guest's memory * where the secret will be set, as VIR_TYPED_PARAM_ULLONG. If not specified, * the address will be determined by the hypervisor. + * + * Since: v8.0.0 + * */ # define VIR_DOMAIN_LAUNCH_SECURITY_SEV_SECRET_SET_ADDRESS "sev-secret-set-address" diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h index 15e4e7ea72..de08dcc118 100644 --- a/include/libvirt/libvirt-host.h +++ b/include/libvirt/libvirt-host.h @@ -80,6 +80,9 @@ typedef virStream *virStreamPtr; * * Macro providing the maximum length of the virSecurityLabel label string. * Note that this value is based on that used by Labeled NFS. + * + * Since: v0.6.1 + * */ # define VIR_SECURITY_LABEL_BUFLEN (4096 + 1) @@ -108,6 +111,9 @@ typedef virSecurityLabel *virSecurityLabelPtr; * VIR_SECURITY_MODEL_BUFLEN: * * Macro providing the maximum length of the virSecurityModel model string. + * + * Since: v0.6.1 + * */ # define VIR_SECURITY_MODEL_BUFLEN (256 + 1) @@ -115,6 +121,9 @@ typedef virSecurityLabel *virSecurityLabelPtr; * VIR_SECURITY_DOI_BUFLEN: * * Macro providing the maximum length of the virSecurityModel doi string. + * + * Since: v0.6.1 + * */ # define VIR_SECURITY_DOI_BUFLEN (256 + 1) @@ -176,6 +185,9 @@ struct _virNodeInfo { * VIR_NODE_CPU_STATS_FIELD_LENGTH: * * Macro providing the field length of virNodeCPUStats + * + * Since: v0.9.3 + * */ # define VIR_NODE_CPU_STATS_FIELD_LENGTH 80 @@ -193,6 +205,9 @@ typedef enum { * * Macro for the cumulative CPU time which was spent by the kernel, * since the node booting up (in nanoseconds). + * + * Since: v0.9.3 + * */ # define VIR_NODE_CPU_STATS_KERNEL "kernel" @@ -201,6 +216,9 @@ typedef enum { * * The cumulative CPU time which was spent by user processes, * since the node booting up (in nanoseconds). + * + * Since: v0.9.3 + * */ # define VIR_NODE_CPU_STATS_USER "user" @@ -209,6 +227,9 @@ typedef enum { * * The cumulative idle CPU time, * since the node booting up (in nanoseconds). + * + * Since: v0.9.3 + * */ # define VIR_NODE_CPU_STATS_IDLE "idle" @@ -217,6 +238,9 @@ typedef enum { * * The cumulative I/O wait CPU time, * since the node booting up (in nanoseconds). + * + * Since: v0.9.3 + * */ # define VIR_NODE_CPU_STATS_IOWAIT "iowait" @@ -225,6 +249,9 @@ typedef enum { * * The cumulative interrupt CPU time, * since the node booting up (in nanoseconds). + * + * Since: v1.2.2 + * */ # define VIR_NODE_CPU_STATS_INTR "intr" @@ -234,6 +261,9 @@ typedef enum { * The CPU utilization of a node. * The usage value is in percent and 100% represents all CPUs of * the node. + * + * Since: v0.9.3 + * */ # define VIR_NODE_CPU_STATS_UTILIZATION "utilization" @@ -254,6 +284,9 @@ struct _virNodeCPUStats { * VIR_NODE_MEMORY_STATS_FIELD_LENGTH: * * Macro providing the field length of virNodeMemoryStats + * + * Since: v0.9.3 + * */ # define VIR_NODE_MEMORY_STATS_FIELD_LENGTH 80 @@ -271,6 +304,9 @@ typedef enum { * * Macro for the total memory of specified cell: * it represents the maximum memory. + * + * Since: v0.9.3 + * */ # define VIR_NODE_MEMORY_STATS_TOTAL "total" @@ -280,6 +316,9 @@ typedef enum { * Macro for the free memory of specified cell: * On Linux, it includes buffer and cached memory, in case of * VIR_NODE_MEMORY_STATS_ALL_CELLS. + * + * Since: v0.9.3 + * */ # define VIR_NODE_MEMORY_STATS_FREE "free" @@ -288,6 +327,9 @@ typedef enum { * * Macro for the buffer memory: On Linux, it is only returned in case of * VIR_NODE_MEMORY_STATS_ALL_CELLS. + * + * Since: v0.9.3 + * */ # define VIR_NODE_MEMORY_STATS_BUFFERS "buffers" @@ -296,6 +338,9 @@ typedef enum { * * Macro for the cached memory: On Linux, it is only returned in case of * VIR_NODE_MEMORY_STATS_ALL_CELLS. + * + * Since: v0.9.3 + * */ # define VIR_NODE_MEMORY_STATS_CACHED "cached" @@ -317,6 +362,9 @@ struct _virNodeMemoryStats { * * Macro for typed parameter that represents how many present pages * to scan before the shared memory service goes to sleep. + * + * Since: v0.10.2 + * */ # define VIR_NODE_MEMORY_SHARED_PAGES_TO_SCAN "shm_pages_to_scan" @@ -325,6 +373,9 @@ struct _virNodeMemoryStats { * * Macro for typed parameter that represents how many milliseconds * the shared memory service should sleep before next scan. + * + * Since: v0.10.2 + * */ # define VIR_NODE_MEMORY_SHARED_SLEEP_MILLISECS "shm_sleep_millisecs" @@ -333,6 +384,9 @@ struct _virNodeMemoryStats { * * Macro for typed parameter that represents how many the shared * memory pages are being used. + * + * Since: v0.10.2 + * */ # define VIR_NODE_MEMORY_SHARED_PAGES_SHARED "shm_pages_shared" @@ -341,6 +395,9 @@ struct _virNodeMemoryStats { * * Macro for typed parameter that represents how many sites are * sharing the pages i.e. how much saved. + * + * Since: v0.10.2 + * */ # define VIR_NODE_MEMORY_SHARED_PAGES_SHARING "shm_pages_sharing" @@ -349,6 +406,9 @@ struct _virNodeMemoryStats { * * Macro for typed parameter that represents how many pages unique * but repeatedly checked for merging. + * + * Since: v0.10.2 + * */ # define VIR_NODE_MEMORY_SHARED_PAGES_UNSHARED "shm_pages_unshared" @@ -357,6 +417,9 @@ struct _virNodeMemoryStats { * * Macro for typed parameter that represents how many pages changing * too fast to be placed in a tree. + * + * Since: v0.10.2 + * */ # define VIR_NODE_MEMORY_SHARED_PAGES_VOLATILE "shm_pages_volatile" @@ -365,6 +428,9 @@ struct _virNodeMemoryStats { * * Macro for typed parameter that represents how many times all * mergeable areas have been scanned. + * + * Since: v0.10.2 + * */ # define VIR_NODE_MEMORY_SHARED_FULL_SCANS "shm_full_scans" @@ -377,6 +443,9 @@ struct _virNodeMemoryStats { * memory area of same NUMA node are merged; When its value is 1, * pages from all nodes can be merged. Other values are reserved * for future use. + * + * Since: v1.0.0 + * */ # define VIR_NODE_MEMORY_SHARED_MERGE_ACROSS_NODES "shm_merge_across_nodes" @@ -406,6 +475,9 @@ int virNodeGetCPUMap(virConnectPtr conn, * * This macro is to calculate the total number of CPUs supported * but not necessary active in the host. + * + * Since: v0.1.4 + * */ @@ -445,6 +517,9 @@ typedef virNodeMemoryStats *virNodeMemoryStatsPtr; * VIR_NODE_SEV_PDH: * * Macro represents the Platform Diffie-Hellman key, as VIR_TYPED_PARAMS_STRING. + * + * Since: v4.5.0 + * */ # define VIR_NODE_SEV_PDH "pdh" @@ -454,6 +529,9 @@ typedef virNodeMemoryStats *virNodeMemoryStatsPtr; * Macro represents the platform certificate chain that includes the platform * endorsement key (PEK), owner certificate authority (OCD) and chip * endorsement key (CEK), as VIR_TYPED_PARAMS_STRING. + * + * Since: v4.5.0 + * */ # define VIR_NODE_SEV_CERT_CHAIN "cert-chain" @@ -461,6 +539,9 @@ typedef virNodeMemoryStats *virNodeMemoryStatsPtr; * VIR_NODE_SEV_CBITPOS: * * Macro represents the CBit Position used by hypervisor when SEV is enabled. + * + * Since: v4.5.0 + * */ # define VIR_NODE_SEV_CBITPOS "cbitpos" @@ -469,6 +550,9 @@ typedef virNodeMemoryStats *virNodeMemoryStatsPtr; * * Macro represents the number of bits we lose in physical address space * when SEV is enabled in the guest. + * + * Since: v4.5.0 + * */ # define VIR_NODE_SEV_REDUCED_PHYS_BITS "reduced-phys-bits" @@ -477,6 +561,9 @@ typedef virNodeMemoryStats *virNodeMemoryStatsPtr; * * Macro represents the number of SEV guests that can * be run on the host, as a VIR_TYPED_PARAM_UINT. + * + * Since: v8.0.0 + * */ # define VIR_NODE_SEV_MAX_GUESTS "max-guests" @@ -485,6 +572,9 @@ typedef virNodeMemoryStats *virNodeMemoryStatsPtr; * * Macro represents the number of SEV-ES guests that can * be run on the host, as a VIR_TYPED_PARAM_UINT. + * + * Since: v8.0.0 + * */ # define VIR_NODE_SEV_MAX_ES_GUESTS "max-es-guests" @@ -582,6 +672,9 @@ VIR_EXPORT_VAR virConnectAuthPtr virConnectAuthPtrDefault; * * This macro provides the length of the buffer required * for virDomainGetUUID() + * + * Since: v0.2.0 + * */ # define VIR_UUID_BUFLEN (16) @@ -591,6 +684,9 @@ VIR_EXPORT_VAR virConnectAuthPtr virConnectAuthPtrDefault; * * This macro provides the length of the buffer required * for virDomainGetUUIDString() + * + * Since: v0.2.0 + * */ # define VIR_UUID_STRING_BUFLEN (36+1) @@ -617,6 +713,9 @@ int virConnectClose (virConnectPtr conn); * VIR_CONNECT_IDENTITY_USER_NAME: * * The operating system user name as VIR_TYPED_PARAM_STRING. + * + * Since: v5.8.0 + * */ # define VIR_CONNECT_IDENTITY_USER_NAME "user-name" @@ -624,6 +723,9 @@ int virConnectClose (virConnectPtr conn); * VIR_CONNECT_IDENTITY_UNIX_USER_ID: * * The UNIX user ID as VIR_TYPED_PARAM_ULLONG. + * + * Since: v5.8.0 + * */ # define VIR_CONNECT_IDENTITY_UNIX_USER_ID "unix-user-id" @@ -631,6 +733,9 @@ int virConnectClose (virConnectPtr conn); * VIR_CONNECT_IDENTITY_GROUP_NAME: * * The operating system group name as VIR_TYPED_PARAM_STRING. + * + * Since: v5.8.0 + * */ # define VIR_CONNECT_IDENTITY_GROUP_NAME "group-name" @@ -638,6 +743,9 @@ int virConnectClose (virConnectPtr conn); * VIR_CONNECT_IDENTITY_UNIX_GROUP_ID: * * The UNIX group ID as VIR_TYPED_PARAM_ULLONG. + * + * Since: v5.8.0 + * */ # define VIR_CONNECT_IDENTITY_UNIX_GROUP_ID "unix-group-id" @@ -645,6 +753,9 @@ int virConnectClose (virConnectPtr conn); * VIR_CONNECT_IDENTITY_PROCESS_ID: * * The operating system process ID as VIR_TYPED_PARAM_LLONG. + * + * Since: v5.8.0 + * */ # define VIR_CONNECT_IDENTITY_PROCESS_ID "process-id" @@ -656,6 +767,9 @@ int virConnectClose (virConnectPtr conn); * The units the time is measured in vary according to the * host operating system. On Linux this is usually clock * ticks (as reported in /proc/$PID/stat field 22). + * + * Since: v5.8.0 + * */ # define VIR_CONNECT_IDENTITY_PROCESS_TIME "process-time" @@ -663,6 +777,9 @@ int virConnectClose (virConnectPtr conn); * VIR_CONNECT_IDENTITY_SASL_USER_NAME: * * The SASL authenticated username as VIR_TYPED_PARAM_STRING + * + * Since: v5.8.0 + * */ # define VIR_CONNECT_IDENTITY_SASL_USER_NAME "sasl-user-name" @@ -670,6 +787,9 @@ int virConnectClose (virConnectPtr conn); * VIR_CONNECT_IDENTITY_X509_DISTINGUISHED_NAME: * * The TLS x509 certificate distinguished named as VIR_TYPED_PARAM_STRING + * + * Since: v5.8.0 + * */ # define VIR_CONNECT_IDENTITY_X509_DISTINGUISHED_NAME "x509-distinguished-name" @@ -677,6 +797,9 @@ int virConnectClose (virConnectPtr conn); * VIR_CONNECT_IDENTITY_SELINUX_CONTEXT: * * The application's SELinux context as VIR_TYPED_PARAM_STRING. + * + * Since: v5.8.0 + * */ # define VIR_CONNECT_IDENTITY_SELINUX_CONTEXT "selinux-context" diff --git a/include/libvirt/libvirt-network.h b/include/libvirt/libvirt-network.h index ad02e4d5f4..161c61de28 100644 --- a/include/libvirt/libvirt-network.h +++ b/include/libvirt/libvirt-network.h @@ -283,6 +283,9 @@ typedef void (*virConnectNetworkEventLifecycleCallback)(virConnectPtr conn, * * Used to cast the event specific callback into the generic one * for use for virConnectNetworkEventRegisterAny() + * + * Since: v1.2.1 + * */ # define VIR_NETWORK_EVENT_CALLBACK(cb) ((virConnectNetworkEventGenericCallback)(cb)) @@ -404,6 +407,9 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port, * VIR_NETWORK_PORT_BANDWIDTH_IN_AVERAGE: * * Macro represents the inbound average of NIC bandwidth, as a uint. + * + * Since: v5.5.0 + * */ # define VIR_NETWORK_PORT_BANDWIDTH_IN_AVERAGE "inbound.average" @@ -411,6 +417,9 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port, * VIR_NETWORK_PORT_BANDWIDTH_IN_PEAK: * * Macro represents the inbound peak of NIC bandwidth, as a uint. + * + * Since: v5.5.0 + * */ # define VIR_NETWORK_PORT_BANDWIDTH_IN_PEAK "inbound.peak" @@ -418,6 +427,9 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port, * VIR_NETWORK_PORT_BANDWIDTH_IN_BURST: * * Macro represents the inbound burst of NIC bandwidth, as a uint. + * + * Since: v5.5.0 + * */ # define VIR_NETWORK_PORT_BANDWIDTH_IN_BURST "inbound.burst" @@ -425,6 +437,9 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port, * VIR_NETWORK_PORT_BANDWIDTH_IN_FLOOR: * * Macro represents the inbound floor of NIC bandwidth, as a uint. + * + * Since: v5.5.0 + * */ # define VIR_NETWORK_PORT_BANDWIDTH_IN_FLOOR "inbound.floor" @@ -432,6 +447,9 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port, * VIR_NETWORK_PORT_BANDWIDTH_OUT_AVERAGE: * * Macro represents the outbound average of NIC bandwidth, as a uint. + * + * Since: v5.5.0 + * */ # define VIR_NETWORK_PORT_BANDWIDTH_OUT_AVERAGE "outbound.average" @@ -439,6 +457,9 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port, * VIR_NETWORK_PORT_BANDWIDTH_OUT_PEAK: * * Macro represents the outbound peak of NIC bandwidth, as a uint. + * + * Since: v5.5.0 + * */ # define VIR_NETWORK_PORT_BANDWIDTH_OUT_PEAK "outbound.peak" @@ -446,6 +467,9 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port, * VIR_NETWORK_PORT_BANDWIDTH_OUT_BURST: * * Macro represents the outbound burst of NIC bandwidth, as a uint. + * + * Since: v5.5.0 + * */ # define VIR_NETWORK_PORT_BANDWIDTH_OUT_BURST "outbound.burst" diff --git a/include/libvirt/libvirt-nodedev.h b/include/libvirt/libvirt-nodedev.h index 4e68d09814..8fdded2f34 100644 --- a/include/libvirt/libvirt-nodedev.h +++ b/include/libvirt/libvirt-nodedev.h @@ -156,6 +156,9 @@ int virNodeDeviceIsActive(virNodeDevicePtr dev); * * Used to cast the event specific callback into the generic one * for use for virConnectNodeDeviceEventRegisterAny() + * + * Since: v2.2.0 + * */ # define VIR_NODE_DEVICE_EVENT_CALLBACK(cb)((virConnectNodeDeviceEventGenericCallback)(cb)) diff --git a/include/libvirt/libvirt-secret.h b/include/libvirt/libvirt-secret.h index 94722a46af..cee27155a3 100644 --- a/include/libvirt/libvirt-secret.h +++ b/include/libvirt/libvirt-secret.h @@ -122,6 +122,9 @@ int virSecretFree (virSecretPtr secret); * * Used to cast the event specific callback into the generic one * for use for virConnectSecretEventRegisterAny() + * + * Since: v3.0.0 + * */ # define VIR_SECRET_EVENT_CALLBACK(cb)((virConnectSecretEventGenericCallback)(cb)) diff --git a/include/libvirt/libvirt-storage.h b/include/libvirt/libvirt-storage.h index 9ffcdc6180..9bd437bf66 100644 --- a/include/libvirt/libvirt-storage.h +++ b/include/libvirt/libvirt-storage.h @@ -422,6 +422,9 @@ int virStoragePoolIsPersistent(virStoragePoolPtr pool); * * Used to cast the event specific callback into the generic one * for use for virConnectStoragePoolEventRegisterAny() + * + * Since: v2.0.0 + * */ # define VIR_STORAGE_POOL_EVENT_CALLBACK(cb)((virConnectStoragePoolEventGenericCallback)(cb)) -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given typedef was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso@redhat.com> --- include/libvirt/libvirt-domain-checkpoint.h | 34 +- include/libvirt/libvirt-domain-snapshot.h | 40 +- include/libvirt/libvirt-domain.h | 734 ++++++++++++++++++-- include/libvirt/libvirt-event.h | 3 + include/libvirt/libvirt-host.h | 120 +++- include/libvirt/libvirt-interface.h | 25 +- include/libvirt/libvirt-network.h | 77 +- include/libvirt/libvirt-nodedev.h | 22 +- include/libvirt/libvirt-nwfilter.h | 25 +- include/libvirt/libvirt-secret.h | 36 +- include/libvirt/libvirt-storage.h | 133 +++- include/libvirt/libvirt-stream.h | 18 + include/libvirt/virterror.h | 19 + 13 files changed, 1212 insertions(+), 74 deletions(-) diff --git a/include/libvirt/libvirt-domain-checkpoint.h b/include/libvirt/libvirt-domain-checkpoint.h index a59578b857..5a53717175 100644 --- a/include/libvirt/libvirt-domain-checkpoint.h +++ b/include/libvirt/libvirt-domain-checkpoint.h @@ -34,6 +34,9 @@ * a domain. A checkpoint is useful for tracking which portions of the * domain disks have been altered since a point in time, but by itself does * not allow reverting back to that point in time. + * + * Since: v5.2.0 + * */ typedef struct _virDomainCheckpoint virDomainCheckpoint; @@ -43,6 +46,9 @@ typedef struct _virDomainCheckpoint virDomainCheckpoint; * A virDomainCheckpointPtr is pointer to a virDomainCheckpoint * private structure, and is the type used to reference a domain * checkpoint in the API. + * + * Since: v5.2.0 + * */ typedef virDomainCheckpoint *virDomainCheckpointPtr; @@ -50,6 +56,12 @@ const char *virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint); virDomainPtr virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint); virConnectPtr virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint); +/** + * virDomainCheckpointCreateFlags: + * + * Since: v5.6.0 + * + */ typedef enum { VIR_DOMAIN_CHECKPOINT_CREATE_REDEFINE = (1 << 0), /* Restore or alter metadata (Since: v5.6.0) */ @@ -65,7 +77,12 @@ typedef enum { virDomainCheckpointPtr virDomainCheckpointCreateXML(virDomainPtr domain, const char *xmlDesc, unsigned int flags); - +/** + * virDomainCheckpointXMLFlags: + * + * Since: v5.6.0 + * + */ typedef enum { VIR_DOMAIN_CHECKPOINT_XML_SECURE = (1 << 0), /* Include sensitive data (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_XML_NO_DOMAIN = (1 << 1), /* Suppress <domain> @@ -86,7 +103,11 @@ char *virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, * flag (1<<0) depends on which function it is passed to; but serves * to toggle the per-call default of whether the listing is shallow or * recursive. Remaining bits come in groups; if all bits from a group - * are 0, then that group is not used to filter results. */ + * are 0, then that group is not used to filter results. + * + * Since: v5.6.0 + * + */ typedef enum { VIR_DOMAIN_CHECKPOINT_LIST_ROOTS = (1 << 0), /* Filter by checkpoints with no parents, when @@ -123,7 +144,14 @@ virDomainCheckpointPtr virDomainCheckpointLookupByName(virDomainPtr domain, virDomainCheckpointPtr virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint, unsigned int flags); -/* Delete a checkpoint */ +/** + * virDomainCheckpointDeleteFlags: + * + * Delete a checkpoint + * + * Since: v5.6.0 + * + */ typedef enum { VIR_DOMAIN_CHECKPOINT_DELETE_CHILDREN = (1 << 0), /* Also delete children (Since: v5.6.0) */ VIR_DOMAIN_CHECKPOINT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata (Since: v5.6.0) */ diff --git a/include/libvirt/libvirt-domain-snapshot.h b/include/libvirt/libvirt-domain-snapshot.h index 5dffabb764..cdf82b29ce 100644 --- a/include/libvirt/libvirt-domain-snapshot.h +++ b/include/libvirt/libvirt-domain-snapshot.h @@ -34,6 +34,9 @@ * a domain. A snapshot captures the state of the domain at a point in * time, with the intent that the guest can be reverted back to that * state at a later time. + * + * Since: v0.8.0 + * */ typedef struct _virDomainSnapshot virDomainSnapshot; @@ -42,6 +45,9 @@ typedef struct _virDomainSnapshot virDomainSnapshot; * * A virDomainSnapshotPtr is pointer to a virDomainSnapshot private structure, * and is the type used to reference a domain snapshot in the API. + * + * Since: v0.8.0 + * */ typedef virDomainSnapshot *virDomainSnapshotPtr; @@ -49,6 +55,12 @@ const char *virDomainSnapshotGetName(virDomainSnapshotPtr snapshot); virDomainPtr virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot); virConnectPtr virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot); +/** + * virDomainSnapshotCreateFlags: + * + * Since: v0.9.5 + * + */ typedef enum { VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE = (1 << 0), /* Restore or alter metadata (Since: v0.9.5) */ @@ -79,7 +91,12 @@ typedef enum { virDomainSnapshotPtr virDomainSnapshotCreateXML(virDomainPtr domain, const char *xmlDesc, unsigned int flags); - +/** + * virDomainSnapshotXMLFlags: + * + * Since: v5.1.0 + * + */ typedef enum { VIR_DOMAIN_SNAPSHOT_XML_SECURE = VIR_DOMAIN_XML_SECURE, /* dump security sensitive information too (Since: v5.1.0) */ } virDomainSnapshotXMLFlags; @@ -98,7 +115,11 @@ char *virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot, * of flag (1<<0) depends on which function it is passed to; but serves * to toggle the per-call default of whether the listing is shallow or * recursive. Remaining bits come in groups; if all bits from a group are - * 0, then that group is not used to filter results. */ + * 0, then that group is not used to filter results. + * + * Since: v0.9.5 + * + */ typedef enum { VIR_DOMAIN_SNAPSHOT_LIST_ROOTS = (1 << 0), /* Filter by snapshots with no parents, when @@ -194,6 +215,12 @@ int virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot, int virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot, unsigned int flags); +/** + * virDomainSnapshotRevertFlags: + * + * Since: v0.9.5 + * + */ typedef enum { VIR_DOMAIN_SNAPSHOT_REVERT_RUNNING = 1 << 0, /* Run after revert (Since: v0.9.5) */ VIR_DOMAIN_SNAPSHOT_REVERT_PAUSED = 1 << 1, /* Pause after revert (Since: v0.9.5) */ @@ -208,7 +235,14 @@ typedef enum { int virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot, unsigned int flags); -/* Delete a snapshot */ +/** + * virDomainSnapshotDeleteFlags: + * + * Delete a snapshot + * + * Since: v0.8.0 + * + */ typedef enum { VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN = (1 << 0), /* Also delete children (Since: v0.8.0) */ VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata (Since: v0.9.5) */ diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 01ea2a750f..5654a50c7e 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -32,6 +32,9 @@ * virDomain: * * a virDomain is a private structure representing a domain. + * + * Since: v0.0.1 + * */ typedef struct _virDomain virDomain; @@ -40,6 +43,9 @@ typedef struct _virDomain virDomain; * * a virDomainPtr is pointer to a virDomain private structure, this is the * type used to reference a domain in the API. + * + * Since: v0.0.1 + * */ typedef virDomain *virDomainPtr; @@ -47,6 +53,9 @@ typedef virDomain *virDomainPtr; * virDomainState: * * A domain may be in different states at a given point in time + * + * Since: v0.0.1 + * */ typedef enum { VIR_DOMAIN_NOSTATE = 0, /* no state (Since: v0.0.1) */ @@ -71,6 +80,12 @@ typedef enum { # endif } virDomainState; +/** + * virDomainNostateReason: + * + * Since: v0.9.2 + * + */ typedef enum { VIR_DOMAIN_NOSTATE_UNKNOWN = 0, /* (Since: v0.9.2) */ @@ -79,6 +94,12 @@ typedef enum { # endif } virDomainNostateReason; +/** + * virDomainRunningReason: + * + * Since: v0.9.2 + * + */ typedef enum { VIR_DOMAIN_RUNNING_UNKNOWN = 0, /* (Since: v0.9.2) */ VIR_DOMAIN_RUNNING_BOOTED = 1, /* normal startup from boot (Since: v0.9.2) */ @@ -98,6 +119,12 @@ typedef enum { # endif } virDomainRunningReason; +/** + * virDomainBlockedReason: + * + * Since: v0.9.2 + * + */ typedef enum { VIR_DOMAIN_BLOCKED_UNKNOWN = 0, /* the reason is unknown (Since: v0.9.2) */ @@ -106,6 +133,12 @@ typedef enum { # endif } virDomainBlockedReason; +/** + * virDomainPausedReason: + * + * Since: v0.9.2 + * + */ typedef enum { VIR_DOMAIN_PAUSED_UNKNOWN = 0, /* the reason is unknown (Since: v0.9.2) */ VIR_DOMAIN_PAUSED_USER = 1, /* paused on user request (Since: v0.9.2) */ @@ -127,6 +160,12 @@ typedef enum { # endif } virDomainPausedReason; +/** + * virDomainShutdownReason: + * + * Since: v0.9.2 + * + */ typedef enum { VIR_DOMAIN_SHUTDOWN_UNKNOWN = 0, /* the reason is unknown (Since: v0.9.2) */ VIR_DOMAIN_SHUTDOWN_USER = 1, /* shutting down on user request (Since: v0.9.2) */ @@ -136,6 +175,12 @@ typedef enum { # endif } virDomainShutdownReason; +/** + * virDomainShutoffReason: + * + * Since: v0.9.2 + * + */ typedef enum { VIR_DOMAIN_SHUTOFF_UNKNOWN = 0, /* the reason is unknown (Since: v0.9.2) */ VIR_DOMAIN_SHUTOFF_SHUTDOWN = 1, /* normal shutdown (Since: v0.9.2) */ @@ -153,6 +198,12 @@ typedef enum { # endif } virDomainShutoffReason; +/** + * virDomainCrashedReason: + * + * Since: v0.9.2 + * + */ typedef enum { VIR_DOMAIN_CRASHED_UNKNOWN = 0, /* crashed for unknown reason (Since: v0.9.2) */ VIR_DOMAIN_CRASHED_PANICKED = 1, /* domain panicked (Since: v1.1.1) */ @@ -162,6 +213,12 @@ typedef enum { # endif } virDomainCrashedReason; +/** + * virDomainPMSuspendedReason: + * + * Since: v0.9.11 + * + */ typedef enum { VIR_DOMAIN_PMSUSPENDED_UNKNOWN = 0, /* (Since: v0.9.11) */ @@ -170,6 +227,12 @@ typedef enum { # endif } virDomainPMSuspendedReason; +/** + * virDomainPMSuspendedDiskReason: + * + * Since: v1.0.0 + * + */ typedef enum { VIR_DOMAIN_PMSUSPENDED_DISK_UNKNOWN = 0, /* (Since: v1.0.0) */ @@ -182,6 +245,9 @@ typedef enum { * virDomainControlState: * * Current state of a control interface to the domain. + * + * Since: v0.9.3 + * */ typedef enum { VIR_DOMAIN_CONTROL_OK = 0, /* operational, ready to accept commands (Since: v0.9.3) */ @@ -202,6 +268,9 @@ typedef enum { * virDomainControlErrorReason: * * Reason for the error state. + * + * Since: v1.2.14 + * */ typedef enum { VIR_DOMAIN_CONTROL_ERROR_REASON_NONE = 0, /* server didn't provide a @@ -223,6 +292,9 @@ typedef enum { * * Structure filled in by virDomainGetControlInfo and providing details about * current state of control interface to a domain. + * + * Since: v0.9.3 + * */ typedef struct _virDomainControlInfo virDomainControlInfo; struct _virDomainControlInfo { @@ -238,6 +310,9 @@ struct _virDomainControlInfo { * virDomainControlInfoPtr: * * Pointer to virDomainControlInfo structure. + * + * Since: v0.9.3 + * */ typedef virDomainControlInfo *virDomainControlInfoPtr; @@ -258,6 +333,9 @@ typedef virDomainControlInfo *virDomainControlInfoPtr; * (whether or not it is running). * * These enums should not conflict with those of virTypedParameterFlags. + * + * Since: v0.9.2 + * */ typedef enum { VIR_DOMAIN_AFFECT_CURRENT = 0, /* Affect current domain state. (Since: v0.9.2) */ @@ -267,12 +345,14 @@ typedef enum { } virDomainModificationImpact; /** - * virDomainInfoPtr: + * virDomainInfo: * * a virDomainInfo is a structure filled by virDomainGetInfo() and extracting * runtime information for a given active Domain + * + * Since: v0.0.1 + * */ - typedef struct _virDomainInfo virDomainInfo; struct _virDomainInfo { @@ -287,6 +367,9 @@ struct _virDomainInfo { * virDomainInfoPtr: * * a virDomainInfoPtr is a pointer to a virDomainInfo structure. + * + * Since: v0.0.1 + * */ typedef virDomainInfo *virDomainInfoPtr; @@ -296,6 +379,9 @@ typedef virDomainInfo *virDomainInfoPtr; * * Flags OR'ed together to provide specific behaviour when creating a * Domain. + * + * Since: v0.0.1 + * */ typedef enum { VIR_DOMAIN_NONE = 0, /* Default behavior (Since: v0.0.1) */ @@ -489,7 +575,7 @@ int virDomainSetSchedulerParametersFlags (virDomainPtr domain, unsigned int flags); /** - * virDomainBlockStats: + * virDomainBlockStatsStruct: * * Block device stats for virDomainBlockStats. * @@ -497,6 +583,9 @@ int virDomainSetSchedulerParametersFlags (virDomainPtr domain, * that the hypervisor does not support that statistic. * * NB. Here 'long long' means 64 bit integer. + * + * Since: v0.3.3 + * */ typedef struct _virDomainBlockStats virDomainBlockStatsStruct; @@ -512,6 +601,9 @@ struct _virDomainBlockStats { * virDomainBlockStatsPtr: * * A pointer to a virDomainBlockStats structure + * + * Since: v0.3.2 + * */ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; @@ -626,7 +718,7 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; # define VIR_DOMAIN_BLOCK_STATS_ERRS "errs" /** - * virDomainInterfaceStats: + * virDomainInterfaceStatsStruct: * * Network interface stats for virDomainInterfaceStats. * @@ -634,6 +726,9 @@ typedef virDomainBlockStatsStruct *virDomainBlockStatsPtr; * that the hypervisor does not support that statistic. * * NB. Here 'long long' means 64 bit integer. + * + * Since: v0.3.3 + * */ typedef struct _virDomainInterfaceStats virDomainInterfaceStatsStruct; @@ -652,11 +747,19 @@ struct _virDomainInterfaceStats { * virDomainInterfaceStatsPtr: * * A pointer to a virDomainInterfaceStats structure + * + * Since: v0.3.2 + * */ typedef virDomainInterfaceStatsStruct *virDomainInterfaceStatsPtr; /** + * virDomainMemoryStatTags: + * * Memory Statistics Tags: + * + * Since: v0.7.5 + * */ typedef enum { /* The total amount of data read from swap space (in kB). (Since: v0.7.5) */ @@ -774,6 +877,12 @@ typedef enum { # endif } virDomainMemoryStatTags; +/** + * virDomainMemoryStatStruct: + * + * Since: v0.7.5 + * + */ typedef struct _virDomainMemoryStat virDomainMemoryStatStruct; struct _virDomainMemoryStat { @@ -781,10 +890,23 @@ struct _virDomainMemoryStat { unsigned long long val; }; +/** + * virDomainMemoryStatPtr: + * + * Since: v0.7.5 + * + */ typedef virDomainMemoryStatStruct *virDomainMemoryStatPtr; -/* Domain core dump flags. */ +/** + * virDomainCoreDumpFlags: + * + * Domain core dump flags. + * + * Since: v0.7.5 + * + */ typedef enum { VIR_DUMP_CRASH = (1 << 0), /* crash after dump (Since: v0.7.5) */ VIR_DUMP_LIVE = (1 << 1), /* live dump (Since: v0.7.5) */ @@ -797,6 +919,9 @@ typedef enum { * virDomainCoreDumpFormat: * * Values for specifying different formats of domain core dumps. + * + * Since: v1.2.3 + * */ typedef enum { VIR_DOMAIN_CORE_DUMP_FORMAT_RAW, /* dump guest memory in raw format (Since: v1.2.3) */ @@ -819,7 +944,14 @@ typedef enum { # endif } virDomainCoreDumpFormat; -/* Domain migration flags. */ +/** + * virDomainMigrateFlags: + * + * Domain migration flags. + * + * Since: v0.3.2 + * + */ typedef enum { /* Do not pause the domain during migration. The domain's memory will * be transferred to the destination host while the domain is running. @@ -1369,7 +1501,14 @@ int virDomainMigrateSetCompressionCache(virDomainPtr domain, unsigned long long cacheSize, unsigned int flags); -/* Domain migration speed flags. */ +/** + * virDomainMigrateMaxSpeedFlags: + * + * Domain migration speed flags. + * + * Since: v5.1.0 + * + */ typedef enum { /* Set or get maximum speed of post-copy migration. (Since: v5.1.0) */ VIR_DOMAIN_MIGRATE_MAX_SPEED_POSTCOPY = (1 << 0), @@ -1432,6 +1571,12 @@ virDomainPtr virDomainLookupByUUID (virConnectPtr conn, virDomainPtr virDomainLookupByUUIDString (virConnectPtr conn, const char *uuid); +/** + * virDomainShutdownFlagValues: + * + * Since: v0.9.10 + * + */ typedef enum { VIR_DOMAIN_SHUTDOWN_DEFAULT = 0, /* hypervisor choice (Since: v0.9.10) */ VIR_DOMAIN_SHUTDOWN_ACPI_POWER_BTN = (1 << 0), /* Send ACPI event (Since: v0.9.10) */ @@ -1445,6 +1590,12 @@ int virDomainShutdown (virDomainPtr domain); int virDomainShutdownFlags (virDomainPtr domain, unsigned int flags); +/** + * virDomainRebootFlagValues: + * + * Since: v0.9.10 + * + */ typedef enum { VIR_DOMAIN_REBOOT_DEFAULT = 0, /* hypervisor choice (Since: v0.9.10) */ VIR_DOMAIN_REBOOT_ACPI_POWER_BTN = (1 << 0), /* Send ACPI event (Since: v0.9.10) */ @@ -1466,6 +1617,9 @@ int virDomainDestroy (virDomainPtr domain); * * Flags used to provide specific behaviour to the * virDomainDestroyFlags() function + * + * Since: v0.9.4 + * */ typedef enum { VIR_DOMAIN_DESTROY_DEFAULT = 0, /* Default behavior - could lead to data loss!! (Since: v0.9.10) */ @@ -1495,9 +1649,13 @@ int virDomainPMWakeup (virDomainPtr domain, /** * virDomainSaveRestoreFlags: + * * Flags for use in virDomainSaveFlags(), virDomainManagedSave(), * virDomainRestoreFlags(), and virDomainSaveImageDefineXML(). Not all * flags apply to all these functions. + * + * Since: v0.9.4 + * */ typedef enum { VIR_DOMAIN_SAVE_BYPASS_CACHE = 1 << 0, /* Avoid file system cache pollution (Since: v0.9.4) */ @@ -1796,7 +1954,14 @@ int virDomainGetMemoryParameters(virDomainPtr domain, virTypedParameterPtr params, int *nparams, unsigned int flags); -/* Memory size modification flags. */ +/** + * virDomainMemoryModFlags: + * + * Memory size modification flags. + * + * Since: v1.0.0 + * + */ typedef enum { /* See virDomainModificationImpact for these flags. (Since: v1.0.0) */ VIR_DOMAIN_MEM_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, @@ -1814,6 +1979,9 @@ typedef enum { * virDomainNumatuneMemMode: * Representation of the various modes in the <numatune> element of * a domain. + * + * Since: v0.9.9 + * */ typedef enum { VIR_DOMAIN_NUMATUNE_MEM_STRICT = 0, /* (Since: v0.9.9) */ @@ -1879,7 +2047,12 @@ int virDomainSetMemoryStatsPeriod (virDomainPtr domain, int virDomainGetMaxVcpus (virDomainPtr domain); int virDomainGetSecurityLabel (virDomainPtr domain, virSecurityLabelPtr seclabel); - +/** + * virDomainGetHostnameFlags: + * + * Since: v6.1.0 + * + */ typedef enum { VIR_DOMAIN_GET_HOSTNAME_LEASE = (1 << 0), /* Parse DHCP lease file (Since: v6.1.0) */ VIR_DOMAIN_GET_HOSTNAME_AGENT = (1 << 1), /* Query qemu guest agent (Since: v6.1.0) */ @@ -1890,6 +2063,12 @@ char * virDomainGetHostname (virDomainPtr domain, int virDomainGetSecurityLabelList (virDomainPtr domain, virSecurityLabelPtr* seclabels); +/** + * virDomainMetadataType: + * + * Since: v0.9.10 + * + */ typedef enum { VIR_DOMAIN_METADATA_DESCRIPTION = 0, /* Operate on <description> (Since: v0.9.10) */ VIR_DOMAIN_METADATA_TITLE = 1, /* Operate on <title> (Since: v0.9.10) */ @@ -1917,12 +2096,15 @@ virDomainGetMetadata(virDomainPtr domain, /* * XML domain description */ + /** * virDomainXMLFlags: * * Flags available for virDomainGetXMLDesc + * + * Since: v0.3.3 + * */ - typedef enum { VIR_DOMAIN_XML_SECURE = (1 << 0), /* dump security sensitive information too (Since: v0.3.3) */ VIR_DOMAIN_XML_INACTIVE = (1 << 1), /* dump inactive domain information (Since: v0.3.3) */ @@ -1930,6 +2112,12 @@ typedef enum { VIR_DOMAIN_XML_MIGRATABLE = (1 << 3), /* dump XML suitable for migration (Since: v1.0.0) */ } virDomainXMLFlags; +/** + * virDomainSaveImageXMLFlags: + * + * Since: v5.1.0 + * + */ typedef enum { VIR_DOMAIN_SAVE_IMAGE_XML_SECURE = VIR_DOMAIN_XML_SECURE, /* dump security sensitive information too (Since: v5.1.0) */ } virDomainSaveImageXMLFlags; @@ -2055,6 +2243,9 @@ int virDomainBlockPeek (virDomainPtr dom, * virDomainBlockResizeFlags: * * Flags available for virDomainBlockResize(). + * + * Since: v0.9.11 + * */ typedef enum { VIR_DOMAIN_BLOCK_RESIZE_BYTES = 1 << 0, /* size in bytes instead of KiB (Since: v0.9.11) */ @@ -2088,8 +2279,18 @@ int virDomainBlockResize (virDomainPtr dom, * * capacity: logical size from qcow2 header * * allocation: highest qcow extent written for an active domain * * physical: size of the block device container + * + * Since: v0.8.1 + * */ typedef struct _virDomainBlockInfo virDomainBlockInfo; + +/** + * virDomainBlockInfoPtr: + * + * Since: v0.8.1 + * + */ typedef virDomainBlockInfo *virDomainBlockInfoPtr; struct _virDomainBlockInfo { unsigned long long capacity; /* logical size in bytes of the @@ -2116,8 +2317,14 @@ int virDomainMemoryStats (virDomainPtr dom, unsigned int nr_stats, unsigned int flags); -/* Memory peeking flags. */ - +/** + * virDomainMemoryFlags: + * + * Memory peeking flags. + * + * Since: v0.4.4 + * + */ typedef enum { VIR_MEMORY_VIRTUAL = 1 << 0, /* addresses are virtual addresses (Since: v0.4.4) */ VIR_MEMORY_PHYSICAL = 1 << 1, /* addresses are physical addresses (Since: v0.7.0) */ @@ -2129,6 +2336,12 @@ int virDomainMemoryPeek (virDomainPtr dom, void *buffer, unsigned int flags); +/** + * virDomainDefineFlags: + * + * Since: v1.2.12 + * + */ typedef enum { VIR_DOMAIN_DEFINE_VALIDATE = (1 << 0), /* Validate the XML document against schema (Since: v1.2.12) */ } virDomainDefineFlags; @@ -2144,6 +2357,12 @@ virDomainPtr virDomainDefineXMLFlags (virConnectPtr conn, unsigned int flags); int virDomainUndefine (virDomainPtr domain); +/** + * virDomainUndefineFlagsValues: + * + * Since: v0.9.4 + * + */ typedef enum { VIR_DOMAIN_UNDEFINE_MANAGED_SAVE = (1 << 0), /* Also remove any managed save (Since: v0.9.4) */ @@ -2173,6 +2392,8 @@ int virConnectListDefinedDomains (virConnectPtr conn, * Flags used to tune which domains are listed by virConnectListAllDomains(). * Note that these flags come in groups; if all bits from a group are 0, * then that group is not used to filter results. + * + * Since: v0.9.13 */ typedef enum { VIR_CONNECT_LIST_DOMAINS_ACTIVE = 1 << 0, /* (Since: v0.9.13) */ @@ -2217,9 +2438,13 @@ int virDomainSetAutostart (virDomainPtr domain, int autostart); /** - * virVcpuInfo: structure for information about a virtual CPU in a domain. + * virVcpuState: + * + * structure for information about a virtual CPU in a domain. + * + * Since: v0.1.4 + * */ - typedef enum { VIR_VCPU_OFFLINE = 0, /* the virtual CPU is offline (Since: v0.1.4) */ VIR_VCPU_RUNNING = 1, /* the virtual CPU is running (Since: v0.1.4) */ @@ -2230,11 +2455,23 @@ typedef enum { # endif } virVcpuState; +/** + * virVcpuHostCpuState: + * + * Since: v6.10.0 + * + */ typedef enum { VIR_VCPU_INFO_CPU_OFFLINE = -1, /* the vCPU is offline (Since: v6.10.0) */ VIR_VCPU_INFO_CPU_UNAVAILABLE = -2, /* the hypervisor does not expose real CPU information (Since: v6.10.0) */ } virVcpuHostCpuState; +/** + * virVcpuInfo: + * + * Since: v0.1.4 + * + */ typedef struct _virVcpuInfo virVcpuInfo; struct _virVcpuInfo { unsigned int number; /* virtual CPU number */ @@ -2242,9 +2479,23 @@ struct _virVcpuInfo { unsigned long long cpuTime; /* CPU time used, in nanoseconds */ int cpu; /* real CPU number, or one of the values from virVcpuHostCpuState */ }; + +/** + * virVcpuInfoPtr: + * + * Since: v0.1.4 + * + */ typedef virVcpuInfo *virVcpuInfoPtr; -/* Flags for controlling virtual CPU hot-plugging. */ +/** + * virDomainVcpuFlags: + * + * Flags for controlling virtual CPU hot-plugging. + * + * Since: v1.0.0 + * + */ typedef enum { /* See virDomainModificationImpact for these flags. (Since: v1.0.0) */ VIR_DOMAIN_VCPU_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, @@ -2292,11 +2543,22 @@ int virDomainGetEmulatorPinInfo (virDomainPtr domain, unsigned int flags); /** - * virIOThreadInfo: + * virDomainIOThreadInfo: * * The data structure for information about all IOThreads in a domain + * + * Since: v1.2.14 + * */ typedef struct _virDomainIOThreadInfo virDomainIOThreadInfo; + + +/** + * virDomainIOThreadInfoPtr: + * + * Since: v1.2.14 + * + */ typedef virDomainIOThreadInfo *virDomainIOThreadInfoPtr; struct _virDomainIOThreadInfo { unsigned int iothread_id; /* IOThread ID */ @@ -2493,6 +2755,12 @@ int virDomainGetVcpus (virDomainPtr domain, # define VIR_GET_CPUMAP(cpumaps, maplen, vcpu) (&((cpumaps)[(vcpu) * (maplen)])) +/** + * virDomainDeviceModifyFlags: + * + * Since: v1.0.0 + * + */ typedef enum { /* See virDomainModificationImpact for these flags. (Since: v1.0.0) */ VIR_DOMAIN_DEVICE_MODIFY_CURRENT = VIR_DOMAIN_AFFECT_CURRENT, @@ -2517,7 +2785,20 @@ int virDomainUpdateDeviceFlags(virDomainPtr domain, int virDomainDetachDeviceAlias(virDomainPtr domain, const char *alias, unsigned int flags); +/** + * virDomainStatsRecord: + * + * Since: v1.2.8 + * + */ typedef struct _virDomainStatsRecord virDomainStatsRecord; + +/** + * virDomainStatsRecordPtr: + * + * Since: v1.2.8 + * + */ typedef virDomainStatsRecord *virDomainStatsRecordPtr; struct _virDomainStatsRecord { virDomainPtr dom; @@ -2525,6 +2806,12 @@ struct _virDomainStatsRecord { int nparams; }; +/** + * virDomainStatsTypes: + * + * Since: v1.2.8 + * + */ typedef enum { VIR_DOMAIN_STATS_STATE = (1 << 0), /* return domain state (Since: v1.2.8) */ VIR_DOMAIN_STATS_CPU_TOTAL = (1 << 1), /* return domain CPU info (Since: v1.2.9) */ @@ -2538,6 +2825,12 @@ typedef enum { VIR_DOMAIN_STATS_DIRTYRATE = (1 << 9), /* return domain dirty rate info (Since: v7.2.0) */ } virDomainStatsTypes; +/** + * virConnectGetAllDomainStatsFlags: + * + * Since: v1.2.8 + * + */ typedef enum { VIR_CONNECT_GET_ALL_DOMAINS_STATS_ACTIVE = VIR_CONNECT_LIST_DOMAINS_ACTIVE, /* (Since: v1.2.8) */ VIR_CONNECT_GET_ALL_DOMAINS_STATS_INACTIVE = VIR_CONNECT_LIST_DOMAINS_INACTIVE, /* (Since: v1.2.8) */ @@ -2881,6 +3174,9 @@ int virDomainSetPerfEvents(virDomainPtr dom, * virDomainBlockJobType: * * Describes various possible block jobs. + * + * Since: v0.9.4 + * */ typedef enum { /* Placeholder (Since: v0.9.4) */ @@ -2931,6 +3227,9 @@ typedef enum { * VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC: Request only, do not wait for completion * VIR_DOMAIN_BLOCK_JOB_ABORT_PIVOT: Pivot to new file when ending a copy or * active commit job + * + * Since: v0.9.12 + * */ typedef enum { VIR_DOMAIN_BLOCK_JOB_ABORT_ASYNC = 1 << 0, /* (Since: v0.9.12) */ @@ -2940,17 +3239,37 @@ typedef enum { int virDomainBlockJobAbort(virDomainPtr dom, const char *disk, unsigned int flags); -/* Flags for use with virDomainGetBlockJobInfo */ +/** + * virDomainBlockJobInfoFlags: + * + * Flags for use with virDomainGetBlockJobInfo + * + * Since: v1.2.9 + * + */ typedef enum { VIR_DOMAIN_BLOCK_JOB_INFO_BANDWIDTH_BYTES = 1 << 0, /* bandwidth in bytes/s instead of MiB/s (Since: v1.2.9) */ } virDomainBlockJobInfoFlags; -/* An iterator for monitoring block job operations */ -typedef unsigned long long virDomainBlockJobCursor; - -typedef struct _virDomainBlockJobInfo virDomainBlockJobInfo; -struct _virDomainBlockJobInfo { +/** + * virDomainBlockJobCursor: + * + * An iterator for monitoring block job operations + * + * Since: v0.9.4 + * + */ +typedef unsigned long long virDomainBlockJobCursor; + +/** + * virDomainBlockJobInfo: + * + * Since: v0.9.4 + * + */ +typedef struct _virDomainBlockJobInfo virDomainBlockJobInfo; +struct _virDomainBlockJobInfo { int type; /* virDomainBlockJobType */ unsigned long bandwidth; /* either bytes/s or MiB/s, according to flags */ @@ -2963,13 +3282,27 @@ struct _virDomainBlockJobInfo { virDomainBlockJobCursor cur; virDomainBlockJobCursor end; }; + +/** + * virDomainBlockJobInfoPtr: + * + * Since: v0.9.4 + * + */ typedef virDomainBlockJobInfo *virDomainBlockJobInfoPtr; int virDomainGetBlockJobInfo(virDomainPtr dom, const char *disk, virDomainBlockJobInfoPtr info, unsigned int flags); -/* Flags for use with virDomainBlockJobSetSpeed */ +/** + * virDomainBlockJobSetSpeedFlags: + * + * Flags for use with virDomainBlockJobSetSpeed + * + * Since: v1.2.9 + * + */ typedef enum { VIR_DOMAIN_BLOCK_JOB_SPEED_BANDWIDTH_BYTES = 1 << 0, /* bandwidth in bytes/s instead of MiB/s (Since: v1.2.9) */ @@ -2978,8 +3311,15 @@ typedef enum { int virDomainBlockJobSetSpeed(virDomainPtr dom, const char *disk, unsigned long bandwidth, unsigned int flags); -/* Flags for use with virDomainBlockPull (values chosen to be a subset - * of the flags for virDomainBlockRebase) */ +/** + * virDomainBlockPullFlags: + * + * Flags for use with virDomainBlockPull (values chosen to be a subset of the + * flags for virDomainBlockRebase) + * + * Since: v1.2.9 + * + */ typedef enum { VIR_DOMAIN_BLOCK_PULL_BANDWIDTH_BYTES = 1 << 6, /* bandwidth in bytes/s instead of MiB/s (Since: v1.2.9) */ @@ -2992,6 +3332,9 @@ int virDomainBlockPull(virDomainPtr dom, const char *disk, * virDomainBlockRebaseFlags: * * Flags available for virDomainBlockRebase(). + * + * Since: v0.9.12 + * */ typedef enum { VIR_DOMAIN_BLOCK_REBASE_SHALLOW = 1 << 0, /* Limit copy to top of source @@ -3017,6 +3360,9 @@ int virDomainBlockRebase(virDomainPtr dom, const char *disk, * virDomainBlockCopyFlags: * * Flags available for virDomainBlockCopy(). + * + * Since: v1.2.8 + * */ typedef enum { /* Limit copy to top of source backing chain (Since: v1.2.8) */ @@ -3094,6 +3440,9 @@ int virDomainBlockCopy(virDomainPtr dom, const char *disk, * virDomainBlockCommitFlags: * * Flags available for virDomainBlockCommit(). + * + * Since: v0.10.2 + * */ typedef enum { VIR_DOMAIN_BLOCK_COMMIT_SHALLOW = 1 << 0, /* NULL base means next backing @@ -3350,6 +3699,9 @@ virDomainGetBlockIoTune(virDomainPtr dom, * virDomainDiskErrorCode: * * Disk I/O error. + * + * Since: v0.9.10 + * */ typedef enum { VIR_DOMAIN_DISK_ERROR_NONE = 0, /* no error (Since: v0.9.10) */ @@ -3364,8 +3716,17 @@ typedef enum { /** * virDomainDiskError: * + * Since: v0.9.10 + * */ typedef struct _virDomainDiskError virDomainDiskError; + +/** + * virDomainDiskErrorPtr: + * + * Since: v0.9.10 + * + */ typedef virDomainDiskError *virDomainDiskErrorPtr; struct _virDomainDiskError { @@ -3384,6 +3745,9 @@ int virDomainGetDiskErrors(virDomainPtr dom, * virKeycodeSet: * * Enum to specify which keycode mapping is in use for virDomainSendKey(). + * + * Since: v0.9.3 + * */ typedef enum { VIR_KEYCODE_SET_LINUX = 0, /* (Since: v0.9.3) */ @@ -3436,7 +3800,9 @@ int virDomainSendKey(virDomainPtr domain, int nkeycodes, unsigned int flags); -/* +/** + * virDomainProcessSignal: + * * These just happen to match Linux signal numbers. The numbers * will be mapped to whatever the SIGNUM is in the guest OS in * question by the agent delivering the signal. The names are @@ -3445,6 +3811,9 @@ int virDomainSendKey(virDomainPtr domain, * Do not rely on all values matching Linux though. It is possible * this enum might be extended with new signals which have no * mapping in Linux. + * + * Since: v1.0.1 + * */ typedef enum { VIR_DOMAIN_PROCESS_SIGNAL_NOP = 0, /* No constant in POSIX/Linux (Since: v1.0.1) */ @@ -3545,6 +3914,9 @@ virDomainPtr virDomainCreateLinux (virConnectPtr conn, * virDomainEventType: * * a virDomainEventType is emitted during domain lifecycle events + * + * Since: v0.5.0 + * */ typedef enum { VIR_DOMAIN_EVENT_DEFINED = 0, /* (Since: v0.5.0) */ @@ -3566,6 +3938,9 @@ typedef enum { * virDomainEventDefinedDetailType: * * Details on the cause of a 'defined' lifecycle event + * + * Since: v0.5.0 + * */ typedef enum { VIR_DOMAIN_EVENT_DEFINED_ADDED = 0, /* Newly created config file (Since: v0.5.0) */ @@ -3582,6 +3957,9 @@ typedef enum { * virDomainEventUndefinedDetailType: * * Details on the cause of an 'undefined' lifecycle event + * + * Since: v0.5.0 + * */ typedef enum { VIR_DOMAIN_EVENT_UNDEFINED_REMOVED = 0, /* Deleted the config file (Since: v0.5.0) */ @@ -3596,6 +3974,9 @@ typedef enum { * virDomainEventStartedDetailType: * * Details on the cause of a 'started' lifecycle event + * + * Since: v0.5.0 + * */ typedef enum { VIR_DOMAIN_EVENT_STARTED_BOOTED = 0, /* Normal startup from boot (Since: v0.5.0) */ @@ -3613,6 +3994,9 @@ typedef enum { * virDomainEventSuspendedDetailType: * * Details on the cause of a 'suspended' lifecycle event + * + * Since: v0.5.0 + * */ typedef enum { VIR_DOMAIN_EVENT_SUSPENDED_PAUSED = 0, /* Normal suspend due to admin pause (Since: v0.5.0) */ @@ -3634,6 +4018,9 @@ typedef enum { * virDomainEventResumedDetailType: * * Details on the cause of a 'resumed' lifecycle event + * + * Since: v0.5.0 + * */ typedef enum { VIR_DOMAIN_EVENT_RESUMED_UNPAUSED = 0, /* Normal resume due to admin unpause (Since: v0.5.0) */ @@ -3651,6 +4038,9 @@ typedef enum { * virDomainEventStoppedDetailType: * * Details on the cause of a 'stopped' lifecycle event + * + * Since: v0.5.0 + * */ typedef enum { VIR_DOMAIN_EVENT_STOPPED_SHUTDOWN = 0, /* Normal shutdown (Since: v0.5.0) */ @@ -3671,6 +4061,9 @@ typedef enum { * virDomainEventShutdownDetailType: * * Details on the cause of a 'shutdown' lifecycle event + * + * Since: v0.9.8 + * */ typedef enum { /* Guest finished shutdown sequence (Since: v0.9.8) */ @@ -3696,6 +4089,9 @@ typedef enum { * virDomainEventPMSuspendedDetailType: * * Details on the cause of a 'pmsuspended' lifecycle event + * + * Since: v0.10.2 + * */ typedef enum { VIR_DOMAIN_EVENT_PMSUSPENDED_MEMORY = 0, /* Guest was PM suspended to memory (Since: v0.10.2) */ @@ -3710,6 +4106,9 @@ typedef enum { * virDomainEventCrashedDetailType: * * Details on the cause of a 'crashed' lifecycle event + * + * Since: v1.1.1 + * */ typedef enum { VIR_DOMAIN_EVENT_CRASHED_PANICKED = 0, /* Guest was panicked (Since: v1.1.1) */ @@ -3724,6 +4123,9 @@ typedef enum { * virDomainMemoryFailureRecipientType: * * Recipient of a memory failure event. + * + * Since: v6.9.0 + * */ typedef enum { /* memory failure at hypersivor memory address space (Since: v6.9.0) */ @@ -3742,6 +4144,9 @@ typedef enum { * virDomainMemoryFailureActionType: * * Action of a memory failure event. + * + * Since: v6.9.0 + * */ typedef enum { /* the memory failure could be ignored. This will only be the case for @@ -3779,6 +4184,12 @@ typedef enum { } virDomainMemoryFailureActionType; +/** + * virDomainMemoryFailureFlags: + * + * Since: v6.9.0 + * + */ typedef enum { /* whether a memory failure event is action-required or action-optional * (e.g. a failure during memory scrub). (Since: v6.9.0) */ @@ -3824,6 +4235,12 @@ int virDomainIsActive(virDomainPtr dom); int virDomainIsPersistent(virDomainPtr dom); int virDomainIsUpdated(virDomainPtr dom); +/** + * virDomainJobType: + * + * Since: v0.7.7 + * + */ typedef enum { VIR_DOMAIN_JOB_NONE = 0, /* No job is active (Since: v0.7.7) */ VIR_DOMAIN_JOB_BOUNDED = 1, /* Job with a finite completion time (Since: v0.7.7) */ @@ -3837,7 +4254,20 @@ typedef enum { # endif } virDomainJobType; +/** + * virDomainJobInfo: + * + * Since: v0.7.7 + * + */ typedef struct _virDomainJobInfo virDomainJobInfo; + +/** + * virDomainJobInfoPtr: + * + * Since: v0.7.7 + * + */ typedef virDomainJobInfo *virDomainJobInfoPtr; struct _virDomainJobInfo { /* One of virDomainJobType */ @@ -3878,6 +4308,9 @@ struct _virDomainJobInfo { * * Flags OR'ed together to provide specific behavior when querying domain * job statistics. + * + * Since: v1.2.9 + * */ typedef enum { VIR_DOMAIN_JOB_STATS_COMPLETED = 1 << 0, /* return stats of a recently @@ -3895,6 +4328,12 @@ int virDomainGetJobStats(virDomainPtr domain, unsigned int flags); int virDomainAbortJob(virDomainPtr dom); +/** + * virDomainJobOperation: + * + * Since: v3.3.0 + * + */ typedef enum { VIR_DOMAIN_JOB_OPERATION_UNKNOWN = 0, /* (Since: v3.3.0) */ VIR_DOMAIN_JOB_OPERATION_START = 1, /* (Since: v3.3.0) */ @@ -4386,6 +4825,9 @@ typedef void (*virConnectDomainEventRTCChangeCallback)(virConnectPtr conn, * virDomainEventWatchdogAction: * * The action that is to be taken due to the watchdog device firing + * + * Since: v0.8.0 + * */ typedef enum { VIR_DOMAIN_EVENT_WATCHDOG_NONE = 0, /* No action, watchdog ignored (Since: v0.8.0) */ @@ -4421,6 +4863,9 @@ typedef void (*virConnectDomainEventWatchdogCallback)(virConnectPtr conn, * virDomainEventIOErrorAction: * * The action that is to be taken due to an IO error occurring + * + * Since: v0.8.0 + * */ typedef enum { VIR_DOMAIN_EVENT_IO_ERROR_NONE = 0, /* No action, IO error ignored (Since: v0.8.0) */ @@ -4484,6 +4929,9 @@ typedef void (*virConnectDomainEventIOErrorReasonCallback)(virConnectPtr conn, * virDomainEventGraphicsPhase: * * The phase of the graphics client connection + * + * Since: v0.8.0 + * */ typedef enum { VIR_DOMAIN_EVENT_GRAPHICS_CONNECT = 0, /* Initial socket connection established (Since: v0.8.0) */ @@ -4499,6 +4947,9 @@ typedef enum { * virDomainEventGraphicsAddressType: * * The type of address for the connection + * + * Since: v0.8.0 + * */ typedef enum { VIR_DOMAIN_EVENT_GRAPHICS_ADDRESS_IPV4, /* IPv4 address (Since: v0.8.0) */ @@ -4512,22 +4963,38 @@ typedef enum { /** - * virDomainEventGraphicsAddress: + * _virDomainEventGraphicsAddress: * * The data structure containing connection address details * + * Since: v1.0.0 + * */ struct _virDomainEventGraphicsAddress { int family; /* Address family, virDomainEventGraphicsAddressType */ char *node; /* Address of node (eg IP address, or UNIX path) */ char *service; /* Service name/number (eg TCP port, or NULL) */ }; + +/** + * virDomainEventGraphicsAddress: + * + * Since: v0.8.0 + * + */ typedef struct _virDomainEventGraphicsAddress virDomainEventGraphicsAddress; + +/** + * virDomainEventGraphicsAddressPtr: + * + * Since: v0.8.0 + * + */ typedef virDomainEventGraphicsAddress *virDomainEventGraphicsAddressPtr; /** - * virDomainEventGraphicsSubjectIdentity: + * _virDomainEventGraphicsSubjectIdentity: * * The data structure representing a single identity * @@ -4538,7 +5005,21 @@ struct _virDomainEventGraphicsSubjectIdentity { char *type; /* Type of identity */ char *name; /* Identity value */ }; + +/** + * virDomainEventGraphicsSubjectIdentity: + * + * Since: v0.8.0 + * + */ typedef struct _virDomainEventGraphicsSubjectIdentity virDomainEventGraphicsSubjectIdentity; + +/** + * virDomainEventGraphicsSubjectIdentityPtr: + * + * Since: v0.8.0 + * + */ typedef virDomainEventGraphicsSubjectIdentity *virDomainEventGraphicsSubjectIdentityPtr; @@ -4549,12 +5030,29 @@ typedef virDomainEventGraphicsSubjectIdentity *virDomainEventGraphicsSubjectIden * * A subject will have zero or more identities. The types of * identity differ according to the authentication scheme + * + * Since: v0.8.0 + * */ struct _virDomainEventGraphicsSubject { int nidentity; /* Number of identities in array*/ virDomainEventGraphicsSubjectIdentityPtr identities; /* Array of identities for subject */ }; + +/** + * virDomainEventGraphicsSubject: + * + * Since: v0.8.0 + * + */ typedef struct _virDomainEventGraphicsSubject virDomainEventGraphicsSubject; + +/** + * virDomainEventGraphicsSubjectPtr: + * + * Since: v0.8.0 + * + */ typedef virDomainEventGraphicsSubject *virDomainEventGraphicsSubjectPtr; @@ -4586,6 +5084,9 @@ typedef void (*virConnectDomainEventGraphicsCallback)(virConnectPtr conn, * * Tracks status of a virDomainBlockPull(), virDomainBlockRebase(), * virDomainBlockCopy(), or virDomainBlockCommit() operation + * + * Since: v0.9.4 + * */ typedef enum { VIR_DOMAIN_BLOCK_JOB_COMPLETED = 0, /* (Since: v0.9.4) */ @@ -4633,6 +5134,9 @@ typedef void (*virConnectDomainEventBlockJobCallback)(virConnectPtr conn, * virConnectDomainEventDiskChangeReason: * * The reason describing why this callback is called + * + * Since: v0.9.7 + * */ typedef enum { /* Removable media changed to empty according to startup policy as source @@ -4685,6 +5189,9 @@ typedef void (*virConnectDomainEventDiskChangeCallback)(virConnectPtr conn, * virDomainEventTrayChangeReason: * * The reason describing why the callback was called + * + * Since: v0.9.11 + * */ typedef enum { VIR_DOMAIN_EVENT_TRAY_CHANGE_OPEN = 0, /* (Since: v0.9.11) */ @@ -5302,6 +5809,12 @@ typedef void (*virConnectDomainEventTunableCallback)(virConnectPtr conn, void *opaque); +/** + * virConnectDomainEventAgentLifecycleState: + * + * Since: v1.2.11 + * + */ typedef enum { VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_STATE_CONNECTED = 1, /* agent connected (Since: v1.2.11) */ VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_STATE_DISCONNECTED = 2, /* agent disconnected (Since: v1.2.11) */ @@ -5311,6 +5824,12 @@ typedef enum { # endif } virConnectDomainEventAgentLifecycleState; +/** + * virConnectDomainEventAgentLifecycleReason: + * + * Since: v1.2.11 + * + */ typedef enum { VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_UNKNOWN = 0, /* unknown state change reason (Since: v1.2.11) */ VIR_CONNECT_DOMAIN_EVENT_AGENT_LIFECYCLE_REASON_DOMAIN_STARTED = 1, /* state changed due to domain start (Since: v1.2.11) */ @@ -5438,6 +5957,9 @@ typedef void (*virConnectDomainEventMemoryDeviceSizeChangeCallback)(virConnectPt * An enumeration of supported eventId parameters for * virConnectDomainEventRegisterAny(). Each event id determines which * signature of callback function will be used. + * + * Since: v0.8.0 + * */ typedef enum { VIR_DOMAIN_EVENT_ID_LIFECYCLE = 0, /* virConnectDomainEventCallback (Since: v0.8.0) */ @@ -5494,9 +6016,10 @@ int virConnectDomainEventDeregisterAny(virConnectPtr conn, /** - * virDomainConsoleFlags + * virDomainConsoleFlags: + * + * Since: v0.9.11 * - * Since 0.9.10 */ typedef enum { @@ -5513,9 +6036,9 @@ int virDomainOpenConsole(virDomainPtr dom, unsigned int flags); /** - * virDomainChannelFlags + * virDomainChannelFlags: * - * Since 1.0.2 + * Since: v1.0.2 */ typedef enum { VIR_DOMAIN_CHANNEL_FORCE = (1 << 0), /* abort a (possibly) active channel @@ -5528,6 +6051,12 @@ int virDomainOpenChannel(virDomainPtr dom, virStreamPtr st, unsigned int flags); +/** + * virDomainOpenGraphicsFlags: + * + * Since: v0.9.7 + * + */ typedef enum { VIR_DOMAIN_OPEN_GRAPHICS_SKIPAUTH = (1 << 0), /* (Since: v0.9.7) */ } virDomainOpenGraphicsFlags; @@ -5563,9 +6092,20 @@ int virDomainFSThaw(virDomainPtr dom, * * The data structure containing mounted file systems within a guset * + * Since: v1.2.11 + * + * */ typedef struct _virDomainFSInfo virDomainFSInfo; + +/** + * virDomainFSInfoPtr: + * + * Since: v1.2.11 + * + */ typedef virDomainFSInfo *virDomainFSInfoPtr; + struct _virDomainFSInfo { char *mountpoint; /* path to mount point */ char *name; /* device name in the guest (e.g. "sda1") */ @@ -5584,7 +6124,12 @@ int virDomainGetTime(virDomainPtr dom, long long *seconds, unsigned int *nseconds, unsigned int flags); - +/** + * virDomainSetTimeFlags: + * + * Since: v1.2.5 + * + */ typedef enum { VIR_DOMAIN_TIME_SYNC = (1 << 0), /* Re-sync domain time from domain's RTC (Since: v1.2.5) */ } virDomainSetTimeFlags; @@ -5598,8 +6143,10 @@ int virDomainSetTime(virDomainPtr dom, * virSchedParameterType: * * A scheduler parameter field type. Provided for backwards - * compatibility; virTypedParameterType is the preferred enum since - * 0.9.2. + * compatibility; virTypedParameterType is the preferred enum + * + * Since: v0.2.3 + * */ typedef enum { VIR_DOMAIN_SCHED_FIELD_INT = VIR_TYPED_PARAM_INT, /* (Since: v0.2.3) */ @@ -5637,7 +6184,7 @@ typedef enum { * Provided for backwards compatibility; virTypedParameter is the * preferred alias. * - * Since: v0.9.2 + * Since: v0.2.3 * */ typedef struct _virTypedParameter virSchedParameter; @@ -5648,6 +6195,9 @@ typedef struct _virTypedParameter virSchedParameter; * a virSchedParameterPtr is a pointer to a virSchedParameter structure. * Provided for backwards compatibility; virTypedParameterPtr is the * preferred alias since 0.9.2. + * + * Since: v0.2.3 + * */ typedef virSchedParameter *virSchedParameterPtr; @@ -5655,8 +6205,10 @@ typedef virSchedParameter *virSchedParameterPtr; * virBlkioParameterType: * * A blkio parameter field type. Provided for backwards - * compatibility; virTypedParameterType is the preferred enum since - * 0.9.2. + * compatibility; virTypedParameterType is the preferred enum + * + * Since: v0.9.0 + * */ typedef enum { VIR_DOMAIN_BLKIO_PARAM_INT = VIR_TYPED_PARAM_INT, /* (Since: v0.9.0) */ @@ -5694,7 +6246,7 @@ typedef enum { * Provided for backwards compatibility; virTypedParameter is the * preferred alias. * - * Since: v0.9.2 + * Since: v0.9.0 * */ typedef struct _virTypedParameter virBlkioParameter; @@ -5704,7 +6256,10 @@ typedef struct _virTypedParameter virBlkioParameter; * * a virBlkioParameterPtr is a pointer to a virBlkioParameter structure. * Provided for backwards compatibility; virTypedParameterPtr is the - * preferred alias since 0.9.2. + * preferred alias. + * + * Since: v0.9.0 + * */ typedef virBlkioParameter *virBlkioParameterPtr; @@ -5712,8 +6267,10 @@ typedef virBlkioParameter *virBlkioParameterPtr; * virMemoryParameterType: * * A memory parameter field type. Provided for backwards - * compatibility; virTypedParameterType is the preferred enum since - * 0.9.2. + * compatibility; virTypedParameterType is the preferred enum + * + * Since: v0.8.5 + * */ typedef enum { VIR_DOMAIN_MEMORY_PARAM_INT = VIR_TYPED_PARAM_INT, /* (Since: v0.8.5) */ @@ -5751,7 +6308,7 @@ typedef enum { * Provided for backwards compatibility; virTypedParameter is the * preferred alias. * - * Since: v0.9.2 + * Since: v0.8.5 * */ typedef struct _virTypedParameter virMemoryParameter; @@ -5761,10 +6318,19 @@ typedef struct _virTypedParameter virMemoryParameter; * * a virMemoryParameterPtr is a pointer to a virMemoryParameter structure. * Provided for backwards compatibility; virTypedParameterPtr is the - * preferred alias since 0.9.2. + * preferred alias. + * + * Since: v0.8.5 + * */ typedef virMemoryParameter *virMemoryParameterPtr; +/** + * virDomainInterfaceAddressesSource: + * + * Since: v1.2.14 + * + */ typedef enum { VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_LEASE = 0, /* Parse DHCP lease file (Since: v1.2.14) */ VIR_DOMAIN_INTERFACE_ADDRESSES_SRC_AGENT = 1, /* Query qemu guest agent (Since: v1.2.14) */ @@ -5775,7 +6341,20 @@ typedef enum { # endif } virDomainInterfaceAddressesSource; +/** + * virDomainIPAddress: + * + * Since: v1.2.14 + * + */ typedef struct _virDomainInterfaceIPAddress virDomainIPAddress; + +/** + * virDomainIPAddressPtr: + * + * Since: v1.2.14 + * + */ typedef virDomainIPAddress *virDomainIPAddressPtr; struct _virDomainInterfaceIPAddress { int type; /* virIPAddrType */ @@ -5783,7 +6362,20 @@ struct _virDomainInterfaceIPAddress { unsigned int prefix; /* IP address prefix */ }; +/** + * virDomainInterface: + * + * Since: v1.2.14 + * + */ typedef struct _virDomainInterface virDomainInterface; + +/** + * virDomainInterfacePtr: + * + * Since: v1.2.14 + * + */ typedef virDomainInterface *virDomainInterfacePtr; struct _virDomainInterface { char *name; /* interface name */ @@ -5799,6 +6391,12 @@ int virDomainInterfaceAddresses(virDomainPtr dom, void virDomainInterfaceFree(virDomainInterfacePtr iface); +/** + * virDomainSetUserPasswordFlags: + * + * Since: v1.2.16 + * + */ typedef enum { VIR_DOMAIN_PASSWORD_ENCRYPTED = 1 << 0, /* the password is already encrypted (Since: v1.2.16) */ } virDomainSetUserPasswordFlags; @@ -5832,6 +6430,12 @@ int virDomainSetBlockThreshold(virDomainPtr domain, unsigned long long threshold, unsigned int flags); +/** + * virDomainLifecycle: + * + * Since: v3.9.0 + * + */ typedef enum { VIR_DOMAIN_LIFECYCLE_POWEROFF = 0, /* (Since: v3.9.0) */ VIR_DOMAIN_LIFECYCLE_REBOOT = 1, /* (Since: v3.9.0) */ @@ -5842,6 +6446,12 @@ typedef enum { # endif } virDomainLifecycle; +/** + * virDomainLifecycleAction: + * + * Since: v3.9.0 + * + */ typedef enum { VIR_DOMAIN_LIFECYCLE_ACTION_DESTROY = 0, /* (Since: v3.9.0) */ VIR_DOMAIN_LIFECYCLE_ACTION_RESTART = 1, /* (Since: v3.9.0) */ @@ -5969,6 +6579,12 @@ int virDomainSetLaunchSecurityState(virDomainPtr domain, int nparams, unsigned int flags); +/** + * virDomainGuestInfoTypes: + * + * Since: v5.7.0 + * + */ typedef enum { VIR_DOMAIN_GUEST_INFO_USERS = (1 << 0), /* return active users (Since: v5.7.0) */ VIR_DOMAIN_GUEST_INFO_OS = (1 << 1), /* return OS information (Since: v5.7.0) */ @@ -5985,6 +6601,12 @@ int virDomainGetGuestInfo(virDomainPtr domain, int *nparams, unsigned int flags); +/** + * virDomainAgentResponseTimeoutValues: + * + * Since: v5.10.0 + * + */ typedef enum { VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_BLOCK = -2, /* (Since: v5.10.0) */ VIR_DOMAIN_AGENT_RESPONSE_TIMEOUT_DEFAULT = -1, /* (Since: v5.10.0) */ @@ -5995,6 +6617,12 @@ int virDomainAgentSetResponseTimeout(virDomainPtr domain, int timeout, unsigned int flags); +/** + * virDomainBackupBeginFlags: + * + * Since: v6.0.0 + * + */ typedef enum { VIR_DOMAIN_BACKUP_BEGIN_REUSE_EXTERNAL = (1 << 0), /* reuse separately provided images (Since: v6.0.0) */ @@ -6013,6 +6641,12 @@ int virDomainAuthorizedSSHKeysGet(virDomainPtr domain, char ***keys, unsigned int flags); +/** + * virDomainAuthorizedSSHKeysSetFlags: + * + * Since: v6.10.0 + * + */ typedef enum { VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_APPEND = (1 << 0), /* don't truncate file, just append (Since: v6.10.0) */ VIR_DOMAIN_AUTHORIZED_SSH_KEYS_SET_REMOVE = (1 << 1), /* remove keys, instead of adding them (Since: v6.10.0) */ @@ -6025,6 +6659,12 @@ int virDomainAuthorizedSSHKeysSet(virDomainPtr domain, unsigned int nkeys, unsigned int flags); +/** + * virDomainMessageType: + * + * Since: v7.1.0 + * + */ typedef enum { VIR_DOMAIN_MESSAGE_DEPRECATION = (1 << 0), /* (Since: v7.1.0) */ VIR_DOMAIN_MESSAGE_TAINTING = (1 << 1), /* (Since: v7.1.0) */ @@ -6038,6 +6678,9 @@ int virDomainGetMessages(virDomainPtr domain, * virDomainDirtyRateStatus: * * Details on the cause of a dirty rate calculation status. + * + * Since: v7.2.0 + * */ typedef enum { VIR_DOMAIN_DIRTYRATE_UNSTARTED = 0, /* the dirtyrate calculation has @@ -6058,6 +6701,9 @@ typedef enum { * Flags OR'ed together to provide specific behaviour when calculating dirty page * rate for a Domain * + * + * Since: v8.1.0 + * */ typedef enum { VIR_DOMAIN_DIRTYRATE_MODE_PAGE_SAMPLING = 0, /* default mode - page-sampling (Since: v8.1.0) */ diff --git a/include/libvirt/libvirt-event.h b/include/libvirt/libvirt-event.h index f86a55ecf6..fe2234913f 100644 --- a/include/libvirt/libvirt-event.h +++ b/include/libvirt/libvirt-event.h @@ -34,6 +34,9 @@ * a virEventHandleType is used similar to POLLxxx FD events, but is specific * to libvirt. A client app must translate to, and from POLL events when using * this construct. + * + * Since: v0.5.0 + * */ typedef enum { VIR_EVENT_HANDLE_READABLE = (1 << 0), /* (Since: v0.5.0) */ diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h index de08dcc118..1996ea87c9 100644 --- a/include/libvirt/libvirt-host.h +++ b/include/libvirt/libvirt-host.h @@ -33,6 +33,9 @@ * * a virConnect is a private structure representing a connection to * the Hypervisor. + * + * Since: v0.0.1 + * */ typedef struct _virConnect virConnect; @@ -41,6 +44,9 @@ typedef struct _virConnect virConnect; * * a virConnectPtr is pointer to a virConnect private structure, this is the * type used to reference a connection to the Hypervisor in the API. + * + * Since: v0.0.1 + * */ typedef virConnect *virConnectPtr; @@ -49,6 +55,9 @@ typedef virConnect *virConnectPtr; * * Flags to indicate which system-wide sleep state the host must be * transitioned to. + * + * Since: v0.9.8 + * */ typedef enum { VIR_NODE_SUSPEND_TARGET_MEM = 0, /* (Since: v0.9.8) */ @@ -64,6 +73,9 @@ typedef enum { * virStream: * * a virStream is a private structure representing a data stream. + * + * Since: v0.7.2 + * */ typedef struct _virStream virStream; @@ -72,6 +84,9 @@ typedef struct _virStream virStream; * * a virStreamPtr is pointer to a virStream private structure, this is the * type used to reference a data stream in the API. + * + * Since: v0.7.2 + * */ typedef virStream *virStreamPtr; @@ -92,6 +107,9 @@ typedef virStream *virStreamPtr; * a virSecurityLabel is a structure filled by virDomainGetSecurityLabel(), * providing the security label and associated attributes for the specified * domain. + * + * Since: v0.6.1 + * */ typedef struct _virSecurityLabel virSecurityLabel; @@ -104,6 +122,9 @@ struct _virSecurityLabel { * virSecurityLabelPtr: * * a virSecurityLabelPtr is a pointer to a virSecurityLabel. + * + * Since: v0.6.1 + * */ typedef virSecurityLabel *virSecurityLabelPtr; @@ -133,6 +154,9 @@ typedef virSecurityLabel *virSecurityLabelPtr; * a virSecurityModel is a structure filled by virNodeGetSecurityModel(), * providing the per-hypervisor security model and DOI attributes for the * specified domain. + * + * Since: v0.6.1 + * */ typedef struct _virSecurityModel virSecurityModel; @@ -145,6 +169,9 @@ struct _virSecurityModel { * virSecurityModelPtr: * * a virSecurityModelPtr is a pointer to a virSecurityModel. + * + * Since: v0.6.1 + * */ typedef virSecurityModel *virSecurityModelPtr; @@ -152,7 +179,7 @@ typedef virSecurityModel *virSecurityModelPtr; /* data types related to virNodePtr */ /** - * virNodeInfoPtr: + * virNodeInfo: * * a virNodeInfo is a structure filled by virNodeGetInfo() and providing * the information for the Node. @@ -160,8 +187,9 @@ typedef virSecurityModel *virSecurityModelPtr; * Note that the information in this struct is not guaranteed to be an * accurate relection of the system hardware. See the virNodeGetInfo() * API documentation for further guidance. + * + * Since: v0.1.0 */ - typedef struct _virNodeInfo virNodeInfo; struct _virNodeInfo { @@ -192,9 +220,12 @@ struct _virNodeInfo { # define VIR_NODE_CPU_STATS_FIELD_LENGTH 80 /** - * VIR_NODE_CPU_STATS_ALL_CPUS: + * virNodeGetCPUStatsAllCPUs: * * Value for specifying request for the total CPU time/utilization + * + * Since: v0.9.8 + * */ typedef enum { VIR_NODE_CPU_STATS_ALL_CPUS = -1, /* (Since: v0.9.3) */ @@ -272,6 +303,9 @@ typedef enum { * * a virNodeCPUStats is a structure filled by virNodeGetCPUStats() * providing information about the CPU stats of the node. + * + * Since: v0.9.3 + * */ typedef struct _virNodeCPUStats virNodeCPUStats; @@ -291,9 +325,12 @@ struct _virNodeCPUStats { # define VIR_NODE_MEMORY_STATS_FIELD_LENGTH 80 /** - * VIR_NODE_MEMORY_STATS_ALL_CELLS: + * virNodeGetMemoryStatsAllCells: * * Value for specifying request for the total memory of all cells. + * + * Since: v0.9.8 + * */ typedef enum { VIR_NODE_MEMORY_STATS_ALL_CELLS = -1, /* (Since: v0.9.3) */ @@ -349,6 +386,9 @@ typedef enum { * * a virNodeMemoryStats is a structure filled by virNodeGetMemoryStats() * providing information about the memory of the node. + * + * Since: v0.9.3 + * */ typedef struct _virNodeMemoryStats virNodeMemoryStats; @@ -487,6 +527,9 @@ int virNodeGetCPUMap(virConnectPtr conn, * virNodeInfoPtr: * * a virNodeInfoPtr is a pointer to a virNodeInfo structure. + * + * Since: v0.1.0 + * */ typedef virNodeInfo *virNodeInfoPtr; @@ -495,6 +538,9 @@ typedef virNodeInfo *virNodeInfoPtr; * virNodeCPUStatsPtr: * * a virNodeCPUStatsPtr is a pointer to a virNodeCPUStats structure. + * + * Since: v0.9.3 + * */ typedef virNodeCPUStats *virNodeCPUStatsPtr; @@ -503,6 +549,9 @@ typedef virNodeCPUStats *virNodeCPUStatsPtr; * virNodeMemoryStatsPtr: * * a virNodeMemoryStatsPtr is a pointer to a virNodeMemoryStats structure. + * + * Since: v0.9.3 + * */ typedef virNodeMemoryStats *virNodeMemoryStatsPtr; @@ -584,16 +633,24 @@ int virNodeGetSEVInfo (virConnectPtr conn, unsigned int flags); /** - * virConnectFlags + * virConnectFlags: * * Flags when opening a connection to a hypervisor + * + * Since: v0.4.1 + * */ typedef enum { VIR_CONNECT_RO = (1 << 0), /* A readonly connection (Since: v0.4.1) */ VIR_CONNECT_NO_ALIASES = (1 << 1), /* Don't try to resolve URI aliases (Since: v0.9.7) */ } virConnectFlags; - +/** + * virConnectCredentialType: + * + * Since: v0.4.1 + * + */ typedef enum { VIR_CRED_USERNAME = 1, /* Identity to act as (Since: v0.4.1) */ VIR_CRED_AUTHNAME = 2, /* Identify to authorize as (Since: v0.4.1) */ @@ -619,7 +676,20 @@ struct _virConnectCredential { unsigned int resultlen; /* Length of the result */ }; +/** + * virConnectCredential: + * + * Since: v0.4.1 + * + */ typedef struct _virConnectCredential virConnectCredential; + +/** + * virConnectCredentialPtr: + * + * Since: v0.4.1 + * + */ typedef virConnectCredential *virConnectCredentialPtr; @@ -648,8 +718,20 @@ struct _virConnectAuth { void *cbdata; }; - +/** + * virConnectAuth: + * + * Since: v0.4.1 + * + */ typedef struct _virConnectAuth virConnectAuth; + +/** + * virConnectAuthPtr: + * + * Since: v0.4.1 + * + */ typedef virConnectAuth *virConnectAuthPtr; /* @@ -892,6 +974,12 @@ int virConnectIsAlive(virConnectPtr conn); * CPU specification API */ +/** + * virCPUCompareResult: + * + * Since: v0.7.5 + * + */ typedef enum { VIR_CPU_COMPARE_ERROR = -1, /* (Since: v0.7.5) */ VIR_CPU_COMPARE_INCOMPATIBLE = 0, /* (Since: v0.7.5) */ @@ -903,6 +991,12 @@ typedef enum { # endif } virCPUCompareResult; +/** + * virConnectCompareCPUFlags: + * + * Since: v1.2.6 + * + */ typedef enum { VIR_CONNECT_COMPARE_CPU_FAIL_INCOMPATIBLE = (1 << 0), /* treat incompatible CPUs as failure (Since: v1.2.6) */ @@ -927,9 +1021,12 @@ int virConnectGetCPUModelNames(virConnectPtr conn, unsigned int flags); /** - * virConnectBaselineCPUFlags + * virConnectBaselineCPUFlags: * * Flags when getting XML description of a computed CPU + * + * Since: v1.1.2 + * */ typedef enum { VIR_CONNECT_BASELINE_CPU_EXPAND_FEATURES = (1 << 0), /* show all features (Since: v1.1.2) */ @@ -957,7 +1054,12 @@ int virNodeGetFreePages(virConnectPtr conn, unsigned int cellcount, unsigned long long *counts, unsigned int flags); - +/** + * virNodeAllocPagesFlags: + * + * Since: v1.2.9 + * + */ typedef enum { VIR_NODE_ALLOC_PAGES_ADD = 0, /* Add @pageCounts to the pages pool. This can be used only to size up the pool. (Since: v1.2.9) */ diff --git a/include/libvirt/libvirt-interface.h b/include/libvirt/libvirt-interface.h index 64bcb08c94..b90bf67140 100644 --- a/include/libvirt/libvirt-interface.h +++ b/include/libvirt/libvirt-interface.h @@ -31,6 +31,9 @@ * virInterface: * * a virInterface is a private structure representing a virtual interface. + * + * Since: v0.6.4 + * */ typedef struct _virInterface virInterface; @@ -39,6 +42,9 @@ typedef struct _virInterface virInterface; * * a virInterfacePtr is pointer to a virInterface private structure, this is the * type used to reference a virtual interface in the API. + * + * Since: v0.6.4 + * */ typedef virInterface *virInterfacePtr; @@ -53,10 +59,13 @@ int virConnectNumOfDefinedInterfaces (virConnectPtr conn); int virConnectListDefinedInterfaces (virConnectPtr conn, char **const names, int maxnames); -/* - * virConnectListAllInterfaces: +/** + * virConnectListAllInterfacesFlags: * * Flags used to filter the returned interfaces. + * + * Since: v0.10.2 + * */ typedef enum { VIR_CONNECT_LIST_INTERFACES_INACTIVE = 1 << 0, /* (Since: v0.10.2) */ @@ -75,10 +84,22 @@ virInterfacePtr virInterfaceLookupByMACString (virConnectPtr conn, const char* virInterfaceGetName (virInterfacePtr iface); const char* virInterfaceGetMACString (virInterfacePtr iface); +/** + * virInterfaceXMLFlags: + * + * Since: v0.7.3 + * + */ typedef enum { VIR_INTERFACE_XML_INACTIVE = 1 << 0 /* dump inactive interface information (Since: v0.7.3) */ } virInterfaceXMLFlags; +/** + * virInterfaceDefineFlags: + * + * Since: v7.7.0 + * + */ typedef enum { VIR_INTERFACE_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virInterfaceDefineFlags; diff --git a/include/libvirt/libvirt-network.h b/include/libvirt/libvirt-network.h index 161c61de28..d735611437 100644 --- a/include/libvirt/libvirt-network.h +++ b/include/libvirt/libvirt-network.h @@ -27,6 +27,12 @@ # error "Don't include this file directly, only use libvirt/libvirt.h" # endif +/** + * virNetworkXMLFlags: + * + * Since: v0.9.10 + * + */ typedef enum { VIR_NETWORK_XML_INACTIVE = (1 << 0), /* dump inactive network information (Since: v0.9.10) */ } virNetworkXMLFlags; @@ -35,6 +41,9 @@ typedef enum { * virNetwork: * * a virNetwork is a private structure representing a virtual network. + * + * Since: v0.2.0 + * */ typedef struct _virNetwork virNetwork; @@ -43,6 +52,9 @@ typedef struct _virNetwork virNetwork; * * a virNetworkPtr is pointer to a virNetwork private structure, this is the * type used to reference a virtual network in the API. + * + * Since: v0.2.0 + * */ typedef virNetwork *virNetworkPtr; @@ -51,6 +63,9 @@ typedef virNetwork *virNetworkPtr; * * a virNetworkPort is a private structure representing a virtual network * port + * + * Since: v5.5.0 + * */ typedef struct _virNetworkPort virNetworkPort; @@ -59,6 +74,9 @@ typedef struct _virNetworkPort virNetworkPort; * * a virNetworkPortPtr is pointer to a virNetworkPort private structure, * this is the type used to reference a virtual network port in the API. + * + * Since: v5.5.0 + * */ typedef virNetworkPort *virNetworkPortPtr; @@ -82,11 +100,14 @@ int virConnectNumOfDefinedNetworks (virConnectPtr conn); int virConnectListDefinedNetworks (virConnectPtr conn, char **const names, int maxnames); -/* - * virConnectListAllNetworks: +/** + * virConnectListAllNetworksFlags: * * Flags used to filter the returned networks. Flags in each group * are exclusive attributes of a network. + * + * Since: v0.10.2 + * */ typedef enum { VIR_CONNECT_LIST_NETWORKS_INACTIVE = 1 << 0, /* (Since: v0.10.2) */ @@ -112,7 +133,12 @@ virNetworkPtr virNetworkLookupByUUID (virConnectPtr conn, const unsigned char *uuid); virNetworkPtr virNetworkLookupByUUIDString (virConnectPtr conn, const char *uuid); - +/** + * virNetworkCreateFlags: + * + * Since: v7.8.0 + * + */ typedef enum { VIR_NETWORK_CREATE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.8.0) */ } virNetworkCreateFlags; @@ -125,7 +151,12 @@ virNetworkPtr virNetworkCreateXML (virConnectPtr conn, virNetworkPtr virNetworkCreateXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int flags); - +/** + * virNetworkDefineFlags: + * + * Since: v7.7.0 + * + */ typedef enum { VIR_NETWORK_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virNetworkDefineFlags; @@ -150,6 +181,8 @@ int virNetworkUndefine (virNetworkPtr network); * describes which type of update to perform on a <network> * definition. * + * Since: v0.10.2 + * */ typedef enum { VIR_NETWORK_UPDATE_COMMAND_NONE = 0, /* (invalid (Since: v0.10.2) */ @@ -168,6 +201,8 @@ typedef enum { * describes which section of a <network> definition the provided * xml should be applied to. * + * Since: v0.10.2 + * */ typedef enum { VIR_NETWORK_SECTION_NONE = 0, /* (invalid (Since: v0.10.2) */ @@ -192,6 +227,9 @@ typedef enum { * virNetworkUpdateFlags: * * Flags to control options for virNetworkUpdate() + * + * Since: v0.10.2 + * */ typedef enum { VIR_NETWORK_UPDATE_AFFECT_CURRENT = 0, /* affect live if network is active, @@ -246,6 +284,9 @@ int virNetworkIsPersistent(virNetworkPtr net); * virNetworkEventLifecycleType: * * a virNetworkEventLifecycleType is emitted during network lifecycle events + * + * Since: v1.2.1 + * */ typedef enum { VIR_NETWORK_EVENT_DEFINED = 0, /* (Since: v1.2.1) */ @@ -295,6 +336,9 @@ typedef void (*virConnectNetworkEventLifecycleCallback)(virConnectPtr conn, * An enumeration of supported eventId parameters for * virConnectNetworkEventRegisterAny(). Each event id determines which * signature of callback function will be used. + * + * Since: v1.2.1 + * */ typedef enum { VIR_NETWORK_EVENT_ID_LIFECYCLE = 0, /* virConnectNetworkEventLifecycleCallback (Since: v1.2.1) */ @@ -311,6 +355,12 @@ typedef enum { # endif } virNetworkEventID; +/** + * virIPAddrType: + * + * Since: v1.2.6 + * + */ typedef enum { VIR_IP_ADDR_TYPE_IPV4, /* (Since: v1.2.6) */ VIR_IP_ADDR_TYPE_IPV6, /* (Since: v1.2.6) */ @@ -320,7 +370,20 @@ typedef enum { # endif } virIPAddrType; +/** + * virNetworkDHCPLease: + * + * Since: v1.2.6 + * + */ typedef struct _virNetworkDHCPLease virNetworkDHCPLease; + +/** + * virNetworkDHCPLeasePtr: + * + * Since: v1.2.6 + * + */ typedef virNetworkDHCPLease *virNetworkDHCPLeasePtr; struct _virNetworkDHCPLease { char *iface; /* Network interface name */ @@ -377,6 +440,12 @@ virNetworkPortPtr virNetworkPortLookupByUUIDString(virNetworkPtr net, const char *uuidstr); +/** + * virNetworkPortCreateFlags: + * + * Since: v5.5.0 + * + */ typedef enum { VIR_NETWORK_PORT_CREATE_RECLAIM = (1 << 0), /* reclaim existing used resources (Since: v5.5.0) */ VIR_NETWORK_PORT_CREATE_VALIDATE = (1 << 1), /* Validate the XML document against schema (Since: v7.8.0) */ diff --git a/include/libvirt/libvirt-nodedev.h b/include/libvirt/libvirt-nodedev.h index 8fdded2f34..1bec57fca4 100644 --- a/include/libvirt/libvirt-nodedev.h +++ b/include/libvirt/libvirt-nodedev.h @@ -32,6 +32,9 @@ * virNodeDevice: * * A virNodeDevice contains a node (host) device details. + * + * Since: v0.5.0 + * */ typedef struct _virNodeDevice virNodeDevice; @@ -43,6 +46,9 @@ typedef struct _virNodeDevice virNodeDevice; * one via virNodeDeviceLookupByName, or virNodeDeviceCreate. Be sure * to call virNodeDeviceFree when done using a virNodeDevicePtr obtained * from any of the above functions to avoid leaking memory. + * + * Since: v0.5.0 + * */ typedef virNodeDevice *virNodeDevicePtr; @@ -57,11 +63,15 @@ int virNodeListDevices (virConnectPtr conn, char **const names, int maxnames, unsigned int flags); -/* - * virConnectListAllNodeDevices: +/** + * virConnectListAllNodeDeviceFlags: * * Flags used to filter either by capability or active state, the - * returned node devices. */ + * returned node devices. + * + * Since: v0.10.2 + * + */ typedef enum { VIR_CONNECT_LIST_NODE_DEVICES_CAP_SYSTEM = 1 << 0, /* System capability (Since: v0.10.2) */ VIR_CONNECT_LIST_NODE_DEVICES_CAP_PCI_DEV = 1 << 1, /* PCI device (Since: v0.10.2) */ @@ -168,6 +178,9 @@ int virNodeDeviceIsActive(virNodeDevicePtr dev); * An enumeration of supported eventId parameters for * virConnectNodeDeviceEventRegisterAny(). Each event id determines which * signature of callback function will be used. + * + * Since: v2.2.0 + * */ typedef enum { VIR_NODE_DEVICE_EVENT_ID_LIFECYCLE = 0, /* virConnectNodeDeviceEventLifecycleCallback (Since: v2.2.0) */ @@ -217,6 +230,9 @@ int virConnectNodeDeviceEventDeregisterAny(virConnectPtr conn, * * a virNodeDeviceEventLifecycleType is emitted during node device * lifecycle events + * + * Since: v2.2.0 + * */ typedef enum { VIR_NODE_DEVICE_EVENT_CREATED = 0, /* (Since: v2.2.0) */ diff --git a/include/libvirt/libvirt-nwfilter.h b/include/libvirt/libvirt-nwfilter.h index aa8872e156..18008426c2 100644 --- a/include/libvirt/libvirt-nwfilter.h +++ b/include/libvirt/libvirt-nwfilter.h @@ -31,6 +31,9 @@ * virNWFilter: * * a virNWFilter is a private structure representing a network filter + * + * Since: v0.8.0 + * */ typedef struct _virNWFilter virNWFilter; @@ -39,6 +42,9 @@ typedef struct _virNWFilter virNWFilter; * * a virNWFilterPtr is pointer to a virNWFilter private structure, * this is the type used to reference a network filter in the API. + * + * Since: v0.8.0 + * */ typedef virNWFilter *virNWFilterPtr; @@ -47,6 +53,9 @@ typedef virNWFilter *virNWFilterPtr; * * a virNWFilterBinding is a private structure representing a network * filter binding to a port + * + * Since: v4.5.0 + * */ typedef struct _virNWFilterBinding virNWFilterBinding; @@ -56,6 +65,9 @@ typedef struct _virNWFilterBinding virNWFilterBinding; * a virNWFilterBindingPtr is pointer to a virNWFilterBinding private * structure, this is the type used to reference a network filter * port binding in the API. + * + * Since: v4.5.0 + * */ typedef virNWFilterBinding *virNWFilterBindingPtr; @@ -79,7 +91,12 @@ virNWFilterPtr virNWFilterLookupByUUID (virConnectPtr conn, const unsigned char *uuid); virNWFilterPtr virNWFilterLookupByUUIDString (virConnectPtr conn, const char *uuid); - +/** + * virNWFilterDefineFlags: + * + * Since: v7.7.0 + * + */ typedef enum { VIR_NWFILTER_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virNWFilterDefineFlags; @@ -108,6 +125,12 @@ int virNWFilterFree (virNWFilterPtr nwfilter); * NWFilter information */ +/** + * virNWFilterBindingCreateFlags: + * + * Since: v7.8.0 + * + */ typedef enum { VIR_NWFILTER_BINDING_CREATE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.8.0) */ } virNWFilterBindingCreateFlags; diff --git a/include/libvirt/libvirt-secret.h b/include/libvirt/libvirt-secret.h index cee27155a3..92fd03f726 100644 --- a/include/libvirt/libvirt-secret.h +++ b/include/libvirt/libvirt-secret.h @@ -33,10 +33,26 @@ * * A virSecret stores a secret value (e.g. a passphrase or encryption key) * and associated metadata. + * + * Since: v0.7.1 + * */ typedef struct _virSecret virSecret; + +/** + * virSecretPtr: + * + * Since: v0.7.1 + * + */ typedef virSecret *virSecretPtr; +/** + * virSecretUsageType: + * + * Since: v0.7.1 + * + */ typedef enum { VIR_SECRET_USAGE_TYPE_NONE = 0, /* (Since: v0.7.1) */ VIR_SECRET_USAGE_TYPE_VOLUME = 1, /* (Since: v0.7.1) */ @@ -63,11 +79,14 @@ int virConnectListSecrets (virConnectPtr conn, char **uuids, int maxuuids); -/* - * virConnectListAllSecrets: +/** + * virConnectListAllSecretsFlags: * * Flags used to filter the returned secrets. Flags in each group * are exclusive attributes of a secret. + * + * Since: v0.10.2 + * */ typedef enum { VIR_CONNECT_LIST_SECRETS_EPHEMERAL = 1 << 0, /* kept in memory, never @@ -90,7 +109,12 @@ virSecretPtr virSecretLookupByUUIDString(virConnectPtr conn, virSecretPtr virSecretLookupByUsage(virConnectPtr conn, int usageType, const char *usageID); - +/** + * virSecretDefineFlags: + * + * Since: v7.7.0 + * + */ typedef enum { VIR_SECRET_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virSecretDefineFlags; @@ -134,6 +158,9 @@ int virSecretFree (virSecretPtr secret); * An enumeration of supported eventId parameters for * virConnectSecretEventRegisterAny(). Each event id determines which * signature of callback function will be used. + * + * Since: v3.0.0 + * */ typedef enum { VIR_SECRET_EVENT_ID_LIFECYCLE = 0, /* virConnectSecretEventLifecycleCallback (Since: v3.0.0) */ @@ -183,6 +210,9 @@ int virConnectSecretEventDeregisterAny(virConnectPtr conn, * * a virSecretEventLifecycleType is emitted during secret * lifecycle events + * + * Since: v3.0.0 + * */ typedef enum { VIR_SECRET_EVENT_DEFINED = 0, /* (Since: v3.0.0) */ diff --git a/include/libvirt/libvirt-storage.h b/include/libvirt/libvirt-storage.h index 9bd437bf66..0b27d5d99f 100644 --- a/include/libvirt/libvirt-storage.h +++ b/include/libvirt/libvirt-storage.h @@ -32,6 +32,9 @@ * virStoragePool: * * a virStoragePool is a private structure representing a storage pool + * + * Since: v0.4.1 + * */ typedef struct _virStoragePool virStoragePool; @@ -40,10 +43,19 @@ typedef struct _virStoragePool virStoragePool; * * a virStoragePoolPtr is pointer to a virStoragePool private structure, this is the * type used to reference a storage pool in the API. + * + * Since: v0.4.1 + * */ typedef virStoragePool *virStoragePoolPtr; +/** + * virStoragePoolState: + * + * Since: v0.4.1 + * + */ typedef enum { VIR_STORAGE_POOL_INACTIVE = 0, /* Not running (Since: v0.4.1) */ VIR_STORAGE_POOL_BUILDING = 1, /* Initializing pool, not available (Since: v0.4.1) */ @@ -56,6 +68,12 @@ typedef enum { # endif } virStoragePoolState; +/** + * virStoragePoolBuildFlags: + * + * Since: v0.4.1 + * + */ typedef enum { VIR_STORAGE_POOL_BUILD_NEW = 0, /* Regular build from scratch (Since: v0.4.1) */ VIR_STORAGE_POOL_BUILD_REPAIR = (1 << 0), /* Repair / reinitialize (Since: v0.4.1) */ @@ -64,11 +82,23 @@ typedef enum { VIR_STORAGE_POOL_BUILD_OVERWRITE = (1 << 3), /* Overwrite data (Since: v0.9.5) */ } virStoragePoolBuildFlags; +/** + * virStoragePoolDeleteFlags: + * + * Since: v0.4.1 + * + */ typedef enum { VIR_STORAGE_POOL_DELETE_NORMAL = 0, /* Delete metadata only (fast) (Since: v0.4.1) */ VIR_STORAGE_POOL_DELETE_ZEROED = 1 << 0, /* Clear all data to zeros (slow) (Since: v0.4.1) */ } virStoragePoolDeleteFlags; +/** + * virStoragePoolCreateFlags: + * + * Since: v1.3.1 + * + */ typedef enum { /* Create the pool but do not perform pool build (Since: v1.3.1) */ VIR_STORAGE_POOL_CREATE_NORMAL = 0, @@ -93,6 +123,12 @@ typedef enum { VIR_STORAGE_POOL_CREATE_WITH_BUILD_NO_OVERWRITE = 1 << 2, } virStoragePoolCreateFlags; +/** + * virStoragePoolInfo: + * + * Since: v0.4.1 + * + */ typedef struct _virStoragePoolInfo virStoragePoolInfo; struct _virStoragePoolInfo { @@ -102,6 +138,12 @@ struct _virStoragePoolInfo { unsigned long long available; /* Remaining free space bytes */ }; +/** + * virStoragePoolInfoPtr: + * + * Since: v0.4.1 + * + */ typedef virStoragePoolInfo *virStoragePoolInfoPtr; @@ -109,6 +151,9 @@ typedef virStoragePoolInfo *virStoragePoolInfoPtr; * virStorageVol: * * a virStorageVol is a private structure representing a storage volume + * + * Since: v0.4.1 + * */ typedef struct _virStorageVol virStorageVol; @@ -117,10 +162,19 @@ typedef struct _virStorageVol virStorageVol; * * a virStorageVolPtr is pointer to a virStorageVol private structure, this is the * type used to reference a storage volume in the API. + * + * Since: v0.4.1 + * */ typedef virStorageVol *virStorageVolPtr; +/** + * virStorageVolType: + * + * Since: v0.4.1 + * + */ typedef enum { VIR_STORAGE_VOL_FILE = 0, /* Regular file based volumes (Since: v0.4.1) */ VIR_STORAGE_VOL_BLOCK = 1, /* Block based volumes (Since: v0.4.1) */ @@ -135,12 +189,24 @@ typedef enum { # endif } virStorageVolType; +/** + * virStorageVolDeleteFlags: + * + * Since: v0.4.1 + * + */ typedef enum { VIR_STORAGE_VOL_DELETE_NORMAL = 0, /* Delete metadata only (fast) (Since: v0.4.1) */ VIR_STORAGE_VOL_DELETE_ZEROED = 1 << 0, /* Clear all data to zeros (slow) (Since: v0.4.1) */ VIR_STORAGE_VOL_DELETE_WITH_SNAPSHOTS = 1 << 1, /* Force removal of volume, even if in use (Since: v1.2.21) */ } virStorageVolDeleteFlags; +/** + * virStorageVolWipeAlgorithm: + * + * Since: v0.9.10 + * + */ typedef enum { VIR_STORAGE_VOL_WIPE_ALG_ZERO = 0, /* 1-pass, all zeroes (Since: v0.9.10) */ VIR_STORAGE_VOL_WIPE_ALG_NNSA = 1, /* 4-pass NNSA Policy Letter @@ -175,6 +241,12 @@ typedef enum { # endif } virStorageVolWipeAlgorithm; +/** + * virStorageVolInfoFlags: + * + * Since: v3.0.0 + * + */ typedef enum { VIR_STORAGE_VOL_USE_ALLOCATION = 0, @@ -183,6 +255,12 @@ typedef enum { } virStorageVolInfoFlags; +/** + * virStorageVolInfo: + * + * Since: v0.4.1 + * + */ typedef struct _virStorageVolInfo virStorageVolInfo; struct _virStorageVolInfo { @@ -191,8 +269,21 @@ struct _virStorageVolInfo { unsigned long long allocation; /* Current allocation bytes */ }; + +/** + * virStorageVolInfoPtr: + * + * Since: v0.4.1 + * + */ typedef virStorageVolInfo *virStorageVolInfoPtr; +/** + * virStorageXMLFlags: + * + * Since: v0.9.13 + * + */ typedef enum { VIR_STORAGE_XML_INACTIVE = (1 << 0), /* dump inactive pool/volume information (Since: v0.9.13) */ } virStorageXMLFlags; @@ -228,6 +319,9 @@ int virConnectListDefinedStoragePools(virConnectPtr conn, * Flags used to tune pools returned by virConnectListAllStoragePools(). * Note that these flags come in groups; if all bits from a group are 0, * then that group is not used to filter results. + * + * Since: v1.0.0 + * */ typedef enum { VIR_CONNECT_LIST_STORAGE_POOLS_INACTIVE = 1 << 0, @@ -279,7 +373,12 @@ virStoragePoolPtr virStoragePoolLookupByUUIDString(virConnectPtr conn, virStoragePoolPtr virStoragePoolLookupByVolume (virStorageVolPtr vol); virStoragePoolPtr virStoragePoolLookupByTargetPath(virConnectPtr conn, const char *path); - +/** + * virStoragePoolDefineFlags: + * + * Since: v7.7.0 + * + */ typedef enum { VIR_STORAGE_POOL_DEFINE_VALIDATE = 1 << 0, /* Validate the XML document against schema (Since: v7.7.0) */ } virStoragePoolDefineFlags; @@ -353,6 +452,12 @@ virStorageVolPtr virStorageVolLookupByPath (virConnectPtr conn, const char* virStorageVolGetName (virStorageVolPtr vol); const char* virStorageVolGetKey (virStorageVolPtr vol); +/** + * virStorageVolCreateFlags: + * + * Since: v1.0.1 + * + */ typedef enum { VIR_STORAGE_VOL_CREATE_PREALLOC_METADATA = 1 << 0, /* (Since: v1.0.1) */ VIR_STORAGE_VOL_CREATE_REFLINK = 1 << 1, /* perform a btrfs lightweight copy (Since: v1.2.13) */ @@ -365,7 +470,12 @@ virStorageVolPtr virStorageVolCreateXMLFrom (virStoragePoolPtr pool, const char *xmldesc, virStorageVolPtr clonevol, unsigned int flags); - +/** + * virStorageVolDownloadFlags: + * + * Since: v3.4.0 + * + */ typedef enum { VIR_STORAGE_VOL_DOWNLOAD_SPARSE_STREAM = 1 << 0, /* Use sparse stream (Since: v3.4.0) */ } virStorageVolDownloadFlags; @@ -375,6 +485,13 @@ int virStorageVolDownload (virStorageVolPtr vol, unsigned long long offset, unsigned long long length, unsigned int flags); + +/** + * virStorageVolUploadFlags: + * + * Since: v3.4.0 + * + */ typedef enum { VIR_STORAGE_VOL_UPLOAD_SPARSE_STREAM = 1 << 0, /* Use sparse stream (Since: v3.4.0) */ } virStorageVolUploadFlags; @@ -404,6 +521,12 @@ char * virStorageVolGetXMLDesc (virStorageVolPtr pool, char * virStorageVolGetPath (virStorageVolPtr vol); +/** + * virStorageVolResizeFlags: + * + * Since: v0.9.10 + * + */ typedef enum { VIR_STORAGE_VOL_RESIZE_ALLOCATE = 1 << 0, /* force allocation of new size (Since: v0.9.10) */ VIR_STORAGE_VOL_RESIZE_DELTA = 1 << 1, /* size is relative to current (Since: v0.9.10) */ @@ -434,6 +557,9 @@ int virStoragePoolIsPersistent(virStoragePoolPtr pool); * An enumeration of supported eventId parameters for * virConnectStoragePoolEventRegisterAny(). Each event id determines which * signature of callback function will be used. + * + * Since: v2.0.0 + * */ typedef enum { VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE = 0, /* virConnectStoragePoolEventLifecycleCallback (Since: v2.0.0) */ @@ -483,6 +609,9 @@ int virConnectStoragePoolEventDeregisterAny(virConnectPtr conn, * * a virStoragePoolEventLifecycleType is emitted during storage pool * lifecycle events + * + * Since: v2.0.0 + * */ typedef enum { VIR_STORAGE_POOL_EVENT_DEFINED = 0, /* (Since: v2.0.0) */ diff --git a/include/libvirt/libvirt-stream.h b/include/libvirt/libvirt-stream.h index d69131030b..caf6779cd6 100644 --- a/include/libvirt/libvirt-stream.h +++ b/include/libvirt/libvirt-stream.h @@ -28,6 +28,12 @@ # endif +/** + * virStreamFlags: + * + * Since: v0.7.2 + * + */ typedef enum { VIR_STREAM_NONBLOCK = (1 << 0), /* (Since: v0.7.2) */ } virStreamFlags; @@ -44,6 +50,12 @@ int virStreamRecv(virStreamPtr st, char *data, size_t nbytes); +/** + * virStreamRecvFlagsValues: + * + * Since: v3.4.0 + * + */ typedef enum { VIR_STREAM_RECV_STOP_AT_HOLE = (1 << 0), /* (Since: v3.4.0) */ } virStreamRecvFlagsValues; @@ -229,6 +241,12 @@ int virStreamSparseRecvAll(virStreamPtr stream, virStreamSinkHoleFunc holeHandler, void *opaque); +/** + * virStreamEventType: + * + * Since: v0.7.2 + * + */ typedef enum { VIR_STREAM_EVENT_READABLE = (1 << 0), /* (Since: v0.7.2) */ VIR_STREAM_EVENT_WRITABLE = (1 << 1), /* (Since: v0.7.2) */ diff --git a/include/libvirt/virterror.h b/include/libvirt/virterror.h index 3c1b27a36f..6d15c12358 100644 --- a/include/libvirt/virterror.h +++ b/include/libvirt/virterror.h @@ -34,6 +34,9 @@ extern "C" { * virErrorLevel: * * Indicates the level of an error + * + * Since: v0.1.0 + * */ typedef enum { VIR_ERR_NONE = 0, /* (Since: v0.1.0) */ @@ -46,6 +49,9 @@ typedef enum { * * Indicates where an error may have come from. This should remain * stable, with all additions placed at the end since libvirt 0.1.0. + * + * Since: v0.1.0 + * */ typedef enum { VIR_FROM_NONE = 0, /* (Since: v0.1.0) */ @@ -152,9 +158,19 @@ typedef enum { * The conn, dom and net fields should be used with extreme care. * Reference counts are not incremented so the underlying objects * may be deleted without notice after the error has been delivered. + * + * Since: v0.1.0 + * */ typedef struct _virError virError; + +/** + * virErrorPtr: + * + * Since: v0.1.0 + * + */ typedef virError *virErrorPtr; struct _virError { int code; /* The error code, a virErrorNumber */ @@ -205,6 +221,9 @@ struct _virError { * break; * default: * } + * + * Since: v0.1.0 + * */ typedef enum { VIR_ERR_OK = 0, /* (Since: v0.1.0) */ -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given function was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso@redhat.com> --- include/libvirt/libvirt-domain.h | 75 ++++ include/libvirt/libvirt-event.h | 24 ++ include/libvirt/libvirt-host.h | 6 + include/libvirt/libvirt-network.h | 6 + include/libvirt/libvirt-nodedev.h | 6 + include/libvirt/libvirt-secret.h | 6 + include/libvirt/libvirt-storage.h | 6 + include/libvirt/libvirt-stream.h | 18 + include/libvirt/virterror.h | 3 + src/libvirt-domain-checkpoint.c | 36 ++ src/libvirt-domain-snapshot.c | 63 ++++ src/libvirt-domain.c | 557 +++++++++++++++++++++++++++++- src/libvirt-host.c | 102 ++++++ src/libvirt-interface.c | 63 ++++ src/libvirt-network.c | 135 ++++++++ src/libvirt-nodedev.c | 81 +++++ src/libvirt-nwfilter.c | 72 ++++ src/libvirt-secret.c | 60 ++++ src/libvirt-storage.c | 171 +++++++++ src/libvirt-stream.c | 51 +++ src/libvirt.c | 18 + src/util/virerror.c | 45 +++ src/util/virevent.c | 27 ++ 23 files changed, 1630 insertions(+), 1 deletion(-) diff --git a/include/libvirt/libvirt-domain.h b/include/libvirt/libvirt-domain.h index 5654a50c7e..9199cc9ad3 100644 --- a/include/libvirt/libvirt-domain.h +++ b/include/libvirt/libvirt-domain.h @@ -4215,6 +4215,9 @@ typedef enum { * A callback function to be registered, and called when a domain event occurs * * Returns 0 (the return value is currently ignored) + * + * Since: v0.5.0 + * */ typedef int (*virConnectDomainEventCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4801,6 +4804,9 @@ typedef enum { * have a customization with extra parameters, often with @opaque being * passed in a different parameter position; use VIR_DOMAIN_EVENT_CALLBACK() * when registering an appropriate handler. + * + * Since: v0.8.0 + * */ typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4815,6 +4821,9 @@ typedef void (*virConnectDomainEventGenericCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_RTC_CHANGE with virConnectDomainEventRegisterAny() + * + * Since: v0.8.0 + * */ typedef void (*virConnectDomainEventRTCChangeCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4853,6 +4862,9 @@ typedef enum { * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_WATCHDOG with virConnectDomainEventRegisterAny() * + * Since: v0.8.0 + * + * */ typedef void (*virConnectDomainEventWatchdogCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4889,6 +4901,9 @@ typedef enum { * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_IO_ERROR with virConnectDomainEventRegisterAny() + * + * Since: v0.8.0 + * */ typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn, virDomainPtr dom, @@ -4916,6 +4931,9 @@ typedef void (*virConnectDomainEventIOErrorCallback)(virConnectPtr conn, * Otherwise, @reason will be "", although future strings may be added * if determination of other error types becomes possible. * + * Since: v0.8.1 + * + * */ typedef void (*virConnectDomainEventIOErrorReasonCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5069,6 +5087,9 @@ typedef virDomainEventGraphicsSubject *virDomainEventGraphicsSubjectPtr; * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_GRAPHICS with virConnectDomainEventRegisterAny() + * + * Since: v0.8.0 + * */ typedef void (*virConnectDomainEventGraphicsCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5122,6 +5143,9 @@ typedef enum { * was registered using the newer type of VIR_DOMAIN_EVENT_ID_BLOCK_JOB_2, * then @disk will contain the device target shorthand (the <target * dev='...'/> sub-element, such as "vda"). + * + * Since: v0.9.4 + * */ typedef void (*virConnectDomainEventBlockJobCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5176,6 +5200,9 @@ typedef enum { * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_DISK_CHANGE with virConnectDomainEventRegisterAny() + * + * Since: v0.9.7 + * */ typedef void (*virConnectDomainEventDiskChangeCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5214,6 +5241,9 @@ typedef enum { * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_TRAY_CHANGE with virConnectDomainEventRegisterAny() + * + * Since: v0.9.11 + * */ typedef void (*virConnectDomainEventTrayChangeCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5233,6 +5263,9 @@ typedef void (*virConnectDomainEventTrayChangeCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_PMWAKEUP with virConnectDomainEventRegisterAny() + * + * Since: v0.9.11 + * */ typedef void (*virConnectDomainEventPMWakeupCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5251,6 +5284,9 @@ typedef void (*virConnectDomainEventPMWakeupCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_PMSUSPEND with virConnectDomainEventRegisterAny() + * + * Since: v0.9.11 + * */ typedef void (*virConnectDomainEventPMSuspendCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5267,6 +5303,9 @@ typedef void (*virConnectDomainEventPMSuspendCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_BALLOON_CHANGE with virConnectDomainEventRegisterAny() + * + * Since: v0.10.0 + * */ typedef void (*virConnectDomainEventBalloonChangeCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5285,6 +5324,9 @@ typedef void (*virConnectDomainEventBalloonChangeCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_PMSUSPEND_DISK with virConnectDomainEventRegisterAny() + * + * Since: v1.0.0 + * */ typedef void (*virConnectDomainEventPMSuspendDiskCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5302,6 +5344,9 @@ typedef void (*virConnectDomainEventPMSuspendDiskCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVED with virConnectDomainEventRegisterAny() + * + * Since: v1.1.1 + * */ typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5319,6 +5364,9 @@ typedef void (*virConnectDomainEventDeviceRemovedCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_DEVICE_ADDED with virConnectDomainEventRegisterAny() + * + * Since: v1.2.15 + * */ typedef void (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5338,6 +5386,9 @@ typedef void (*virConnectDomainEventDeviceAddedCallback)(virConnectPtr conn, * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_DEVICE_REMOVAL_FAILED with * virConnectDomainEventRegisterAny(). + * + * Since: v1.3.4 + * */ typedef void (*virConnectDomainEventDeviceRemovalFailedCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5356,6 +5407,9 @@ typedef void (*virConnectDomainEventDeviceRemovalFailedCallback)(virConnectPtr c * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_METADATA_CHANGE with virConnectDomainEventRegisterAny(). + * + * Since: v3.0.0 + * */ typedef void (*virConnectDomainEventMetadataChangeCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5379,6 +5433,9 @@ typedef void (*virConnectDomainEventMetadataChangeCallback)(virConnectPtr conn, * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_MIGRATION_ITERATION with * virConnectDomainEventRegisterAny(). + * + * Since: v1.3.2 + * */ typedef void (*virConnectDomainEventMigrationIterationCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5403,6 +5460,9 @@ typedef void (*virConnectDomainEventMigrationIterationCallback)(virConnectPtr co * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_JOB_COMPLETED with * virConnectDomainEventRegisterAny(). + * + * Since: v1.3.3 + * */ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5801,6 +5861,9 @@ typedef void (*virConnectDomainEventJobCompletedCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_TUNABLE with virConnectDomainEventRegisterAny() + * + * Since: v1.2.9 + * */ typedef void (*virConnectDomainEventTunableCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5853,6 +5916,9 @@ typedef enum { * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_AGENT_LIFECYCLE with virConnectDomainEventRegisterAny() + * + * Since: v1.2.11 + * */ typedef void (*virConnectDomainEventAgentLifecycleCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5882,6 +5948,9 @@ typedef void (*virConnectDomainEventAgentLifecycleCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_BLOCK_THRESHOLD with virConnectDomainEventRegisterAny() + * + * Since: v3.2.0 + * */ typedef void (*virConnectDomainEventBlockThresholdCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5907,6 +5976,9 @@ typedef void (*virConnectDomainEventBlockThresholdCallback)(virConnectPtr conn, * * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_MEMORY_FAILURE with virConnectDomainEventRegisterAny() + * + * Since: v6.9.0 + * */ typedef void (*virConnectDomainEventMemoryFailureCallback)(virConnectPtr conn, virDomainPtr dom, @@ -5931,6 +6003,9 @@ typedef void (*virConnectDomainEventMemoryFailureCallback)(virConnectPtr conn, * The callback signature to use when registering for an event of type * VIR_DOMAIN_EVENT_ID_MEMORY_DEVICE_SIZE_CHANGE with * virConnectDomainEventRegisterAny(). + * + * Since: v7.9.0 + * */ typedef void (*virConnectDomainEventMemoryDeviceSizeChangeCallback)(virConnectPtr conn, virDomainPtr dom, diff --git a/include/libvirt/libvirt-event.h b/include/libvirt/libvirt-event.h index fe2234913f..7a6483fb8d 100644 --- a/include/libvirt/libvirt-event.h +++ b/include/libvirt/libvirt-event.h @@ -55,6 +55,9 @@ typedef enum { * * Callback for receiving file handle events. The callback will * be invoked once for each event which is pending. + * + * Since: v0.5.0 + * */ typedef void (*virEventHandleCallback)(int watch, int fd, int events, void *opaque); @@ -82,6 +85,9 @@ typedef void (*virEventHandleCallback)(int watch, int fd, int events, void *opaq * * Returns -1 if the file handle cannot be registered, otherwise a handle * watch number to be used for updating and unregistering for events + * + * Since: v0.5.0 + * */ typedef int (*virEventAddHandleFunc)(int fd, int event, virEventHandleCallback cb, @@ -95,6 +101,9 @@ typedef int (*virEventAddHandleFunc)(int fd, int event, * * Part of the EventImpl, this user-provided callback is notified when * events to listen on change + * + * Since: v0.5.0 + * */ typedef void (*virEventUpdateHandleFunc)(int watch, int event); @@ -110,6 +119,9 @@ typedef void (*virEventUpdateHandleFunc)(int watch, int event); * function call, when it is safe to release the user data. * * Returns -1 if the file handle was not registered, 0 upon success + * + * Since: v0.5.0 + * */ typedef int (*virEventRemoveHandleFunc)(int watch); @@ -120,6 +132,9 @@ typedef int (*virEventRemoveHandleFunc)(int watch); * @opaque: user data registered with handle * * callback for receiving timer events + * + * Since: v0.5.0 + * */ typedef void (*virEventTimeoutCallback)(int timer, void *opaque); @@ -138,6 +153,9 @@ typedef void (*virEventTimeoutCallback)(int timer, void *opaque); * this purpose. * * Returns a timer value + * + * Since: v0.5.0 + * */ typedef int (*virEventAddTimeoutFunc)(int timeout, virEventTimeoutCallback cb, @@ -151,6 +169,9 @@ typedef int (*virEventAddTimeoutFunc)(int timeout, * * Part of the EventImpl, this user-defined callback updates an * event timeout. + * + * Since: v0.5.0 + * */ typedef void (*virEventUpdateTimeoutFunc)(int timer, int timeout); @@ -165,6 +186,9 @@ typedef void (*virEventUpdateTimeoutFunc)(int timer, int timeout); * function call, when it is safe to release the user data. * * Returns 0 on success, -1 on failure + * + * Since: v0.5.0 + * */ typedef int (*virEventRemoveTimeoutFunc)(int timer); diff --git a/include/libvirt/libvirt-host.h b/include/libvirt/libvirt-host.h index 1996ea87c9..7c0f487708 100644 --- a/include/libvirt/libvirt-host.h +++ b/include/libvirt/libvirt-host.h @@ -705,6 +705,9 @@ typedef virConnectCredential *virConnectCredentialPtr; * If an interaction cannot be filled, fill in NULL and 0. * * Returns 0 if all interactions were filled, or -1 upon error + * + * Since: v0.4.1 + * */ typedef int (*virConnectAuthCallbackPtr)(virConnectCredentialPtr cred, unsigned int ncred, @@ -912,6 +915,9 @@ int virConnectSetKeepAlive(virConnectPtr conn, * * A callback function to be registered, and called when the connection * is closed. + * + * Since: v0.10.0 + * */ typedef void (*virConnectCloseFunc)(virConnectPtr conn, int reason, diff --git a/include/libvirt/libvirt-network.h b/include/libvirt/libvirt-network.h index d735611437..6957b60ef1 100644 --- a/include/libvirt/libvirt-network.h +++ b/include/libvirt/libvirt-network.h @@ -312,6 +312,9 @@ typedef enum { * * The callback signature to use when registering for an event of type * VIR_NETWORK_EVENT_ID_LIFECYCLE with virConnectNetworkEventRegisterAny() + * + * Since: v1.2.1 + * */ typedef void (*virConnectNetworkEventLifecycleCallback)(virConnectPtr conn, virNetworkPtr net, @@ -415,6 +418,9 @@ int virNetworkGetDHCPLeases(virNetworkPtr network, * have a customization with extra parameters, often with @opaque being * passed in a different parameter position; use VIR_NETWORK_EVENT_CALLBACK() * when registering an appropriate handler. + * + * Since: v1.2.1 + * */ typedef void (*virConnectNetworkEventGenericCallback)(virConnectPtr conn, virNetworkPtr net, diff --git a/include/libvirt/libvirt-nodedev.h b/include/libvirt/libvirt-nodedev.h index 1bec57fca4..12ea115514 100644 --- a/include/libvirt/libvirt-nodedev.h +++ b/include/libvirt/libvirt-nodedev.h @@ -209,6 +209,9 @@ typedef enum { * have a customization with extra parameters, often with @opaque being * passed in a different parameter position; use * VIR_NODE_DEVICE_EVENT_CALLBACK() when registering an appropriate handler. + * + * Since: v2.2.0 + * */ typedef void (*virConnectNodeDeviceEventGenericCallback)(virConnectPtr conn, virNodeDevicePtr dev, @@ -259,6 +262,9 @@ typedef enum { * The callback signature to use when registering for an event of type * VIR_NODE_DEVICE_EVENT_ID_LIFECYCLE with * virConnectNodeDeviceEventRegisterAny() + * + * Since: v2.2.0 + * */ typedef void (*virConnectNodeDeviceEventLifecycleCallback)(virConnectPtr conn, virNodeDevicePtr dev, diff --git a/include/libvirt/libvirt-secret.h b/include/libvirt/libvirt-secret.h index 92fd03f726..e0023f551b 100644 --- a/include/libvirt/libvirt-secret.h +++ b/include/libvirt/libvirt-secret.h @@ -189,6 +189,9 @@ typedef enum { * have a customization with extra parameters, often with @opaque being * passed in a different parameter position; use * VIR_SECRET_EVENT_CALLBACK() when registering an appropriate handler. + * + * Since: v3.0.0 + * */ typedef void (*virConnectSecretEventGenericCallback)(virConnectPtr conn, virSecretPtr secret, @@ -237,6 +240,9 @@ typedef enum { * The callback signature to use when registering for an event of type * VIR_SECRET_EVENT_ID_LIFECYCLE with * virConnectSecretEventRegisterAny() + * + * Since: v3.0.0 + * */ typedef void (*virConnectSecretEventLifecycleCallback)(virConnectPtr conn, virSecretPtr secret, diff --git a/include/libvirt/libvirt-storage.h b/include/libvirt/libvirt-storage.h index 0b27d5d99f..434454f455 100644 --- a/include/libvirt/libvirt-storage.h +++ b/include/libvirt/libvirt-storage.h @@ -588,6 +588,9 @@ typedef enum { * have a customization with extra parameters, often with @opaque being * passed in a different parameter position; use * VIR_STORAGE_POOL_EVENT_CALLBACK() when registering an appropriate handler. + * + * Since: v2.0.0 + * */ typedef void (*virConnectStoragePoolEventGenericCallback)(virConnectPtr conn, virStoragePoolPtr pool, @@ -640,6 +643,9 @@ typedef enum { * The callback signature to use when registering for an event of type * VIR_STORAGE_POOL_EVENT_ID_LIFECYCLE with * virConnectStoragePoolEventRegisterAny() + * + * Since: v2.0.0 + * */ typedef void (*virConnectStoragePoolEventLifecycleCallback)(virConnectPtr conn, virStoragePoolPtr pool, diff --git a/include/libvirt/libvirt-stream.h b/include/libvirt/libvirt-stream.h index caf6779cd6..06f771b40b 100644 --- a/include/libvirt/libvirt-stream.h +++ b/include/libvirt/libvirt-stream.h @@ -100,6 +100,9 @@ int virStreamRecvHole(virStreamPtr, * * Returns the number of bytes filled, 0 upon end * of file, or -1 upon error + * + * Since: v0.7.2 + * */ typedef int (*virStreamSourceFunc)(virStreamPtr st, char *data, @@ -138,6 +141,9 @@ int virStreamSendAll(virStreamPtr st, * * Returns 0 on success, * -1 upon error + * + * Since: v3.4.0 + * */ typedef int (*virStreamSourceHoleFunc)(virStreamPtr st, int *inData, @@ -164,6 +170,9 @@ typedef int (*virStreamSourceHoleFunc)(virStreamPtr st, * * Returns 0 on success, * -1 upon error. + * + * Since: v3.4.0 + * */ typedef int (*virStreamSourceSkipFunc)(virStreamPtr st, long long length, @@ -201,6 +210,9 @@ int virStreamSparseSendAll(virStreamPtr st, * * Returns the number of bytes consumed or -1 upon * error + * + * Since: v0.7.2 + * */ typedef int (*virStreamSinkFunc)(virStreamPtr st, const char *data, @@ -231,6 +243,9 @@ int virStreamRecvAll(virStreamPtr st, * * Returns 0 on success, * -1 upon error + * + * Since: v3.4.0 + * */ typedef int (*virStreamSinkHoleFunc)(virStreamPtr st, long long length, @@ -264,6 +279,9 @@ typedef enum { * * Callback for receiving stream events. The callback will * be invoked once for each event which is pending. + * + * Since: v0.7.2 + * */ typedef void (*virStreamEventCallback)(virStreamPtr stream, int events, void *opaque); diff --git a/include/libvirt/virterror.h b/include/libvirt/virterror.h index 6d15c12358..3ae95cb980 100644 --- a/include/libvirt/virterror.h +++ b/include/libvirt/virterror.h @@ -366,6 +366,9 @@ typedef enum { * @error: the error being raised. * * Signature of a function to use when there is an error raised by the library. + * + * Since: v0.1.0 + * */ typedef void (*virErrorFunc) (void *userData, virErrorPtr error); diff --git a/src/libvirt-domain-checkpoint.c b/src/libvirt-domain-checkpoint.c index 58ee26857d..37a895e771 100644 --- a/src/libvirt-domain-checkpoint.c +++ b/src/libvirt-domain-checkpoint.c @@ -35,6 +35,9 @@ VIR_LOG_INIT("libvirt.domain-checkpoint"); * * Returns a pointer to the name or NULL, the string need not be deallocated * as its lifetime will be the same as the checkpoint object. + * + * Since: v5.6.0 + * */ const char * virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint) @@ -58,6 +61,9 @@ virDomainCheckpointGetName(virDomainCheckpointPtr checkpoint) * call. * * Returns the domain or NULL. + * + * Since: v5.6.0 + * */ virDomainPtr virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint) @@ -81,6 +87,9 @@ virDomainCheckpointGetDomain(virDomainCheckpointPtr checkpoint) * call. * * Returns the connection or NULL. + * + * Since: v5.6.0 + * */ virConnectPtr virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) @@ -138,6 +147,9 @@ virDomainCheckpointGetConnect(virDomainCheckpointPtr checkpoint) * * Returns an (opaque) new virDomainCheckpointPtr on success or NULL * on failure. + * + * Since: v5.6.0 + * */ virDomainCheckpointPtr virDomainCheckpointCreateXML(virDomainPtr domain, @@ -207,6 +219,9 @@ virDomainCheckpointCreateXML(virDomainPtr domain, * * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case * of error. The caller must free() the returned value. + * + * Since: v5.6.0 + * */ char * virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, @@ -281,6 +296,9 @@ virDomainCheckpointGetXMLDesc(virDomainCheckpointPtr checkpoint, * included in the return count, to make iteration easier. The caller is * responsible for calling virDomainCheckpointFree() on each array element, * then calling free() on @checkpoints. + * + * Since: v5.6.0 + * */ int virDomainListAllCheckpoints(virDomainPtr domain, @@ -348,6 +366,9 @@ virDomainListAllCheckpoints(virDomainPtr domain, * in the return count, to make iteration easier. The caller is responsible * for calling virDomainCheckpointFree() on each array element, then calling * free() on @children. + * + * Since: v5.6.0 + * */ int virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint, @@ -394,6 +415,9 @@ virDomainCheckpointListAllChildren(virDomainCheckpointPtr checkpoint, * Returns a domain checkpoint object or NULL in case of failure. If the * domain checkpoint cannot be found, then the VIR_ERR_NO_DOMAIN_CHECKPOINT * error is raised. + * + * Since: v5.6.0 + * */ virDomainCheckpointPtr virDomainCheckpointLookupByName(virDomainPtr domain, @@ -440,6 +464,9 @@ virDomainCheckpointLookupByName(virDomainPtr domain, * Returns a domain checkpoint object or NULL in case of failure. If the * given checkpoint is a root (no parent), then the VIR_ERR_NO_DOMAIN_CHECKPOINT * error is raised. + * + * Since: v5.6.0 + * */ virDomainCheckpointPtr virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint, @@ -493,6 +520,9 @@ virDomainCheckpointGetParent(virDomainCheckpointPtr checkpoint, * silently ignored. * * Returns 0 on success, -1 on error. + * + * Since: v5.6.0 + * */ int virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, @@ -543,6 +573,9 @@ virDomainCheckpointDelete(virDomainCheckpointPtr checkpoint, * increment the reference count. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v5.6.0 + * */ int virDomainCheckpointRef(virDomainCheckpointPtr checkpoint) @@ -566,6 +599,9 @@ virDomainCheckpointRef(virDomainCheckpointPtr checkpoint) * The data structure is freed and should not be used thereafter. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v5.6.0 + * */ int virDomainCheckpointFree(virDomainCheckpointPtr checkpoint) diff --git a/src/libvirt-domain-snapshot.c b/src/libvirt-domain-snapshot.c index 69845918a2..f9fc1d4f2b 100644 --- a/src/libvirt-domain-snapshot.c +++ b/src/libvirt-domain-snapshot.c @@ -35,6 +35,9 @@ VIR_LOG_INIT("libvirt.domain-snapshot"); * * Returns a pointer to the name or NULL, the string need not be deallocated * as its lifetime will be the same as the snapshot object. + * + * Since: v0.9.5 + * */ const char * virDomainSnapshotGetName(virDomainSnapshotPtr snapshot) @@ -58,6 +61,9 @@ virDomainSnapshotGetName(virDomainSnapshotPtr snapshot) * call. * * Returns the domain or NULL. + * + * Since: v0.9.5 + * */ virDomainPtr virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot) @@ -81,6 +87,9 @@ virDomainSnapshotGetDomain(virDomainSnapshotPtr snapshot) * call. * * Returns the connection or NULL. + * + * Since: v0.9.5 + * */ virConnectPtr virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) @@ -213,6 +222,9 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot) * * Returns an (opaque) new virDomainSnapshotPtr on success or NULL on * failure. + * + * Since: v0.8.0 + * */ virDomainSnapshotPtr virDomainSnapshotCreateXML(virDomainPtr domain, @@ -271,6 +283,9 @@ virDomainSnapshotCreateXML(virDomainPtr domain, * * Returns a 0 terminated UTF-8 encoded XML instance or NULL in case * of error. The caller must free() the returned value. + * + * Since: v0.8.0 + * */ char * virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot, @@ -324,6 +339,9 @@ virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot, * virDomainListAllSnapshots(). * * Returns the number of domain snapshots found or -1 in case of error. + * + * Since: v0.8.0 + * */ int virDomainSnapshotNum(virDomainPtr domain, unsigned int flags) @@ -388,6 +406,9 @@ virDomainSnapshotNum(virDomainPtr domain, unsigned int flags) * * Returns the number of domain snapshots found or -1 in case of error. * The caller is responsible to call free() for each member of the array. + * + * Since: v0.8.0 + * */ int virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen, @@ -476,6 +497,9 @@ virDomainSnapshotListNames(virDomainPtr domain, char **names, int nameslen, * in the return count, to make iteration easier. The caller is responsible * for calling virDomainSnapshotFree() on each array element, then calling * free() on @snaps. + * + * Since: v0.9.13 + * */ int virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps, @@ -525,6 +549,9 @@ virDomainListAllSnapshots(virDomainPtr domain, virDomainSnapshotPtr **snaps, * virDomainSnapshotListAllChildren(). * * Returns the number of domain snapshots found or -1 in case of error. + * + * Since: v0.9.7 + * */ int virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags) @@ -591,6 +618,9 @@ virDomainSnapshotNumChildren(virDomainSnapshotPtr snapshot, unsigned int flags) * * Returns the number of domain snapshots found or -1 in case of error. * The caller is responsible to call free() for each member of the array. + * + * Since: v0.9.7 + * */ int virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot, @@ -662,6 +692,9 @@ virDomainSnapshotListChildrenNames(virDomainSnapshotPtr snapshot, * in the return count, to make iteration easier. The caller is responsible * for calling virDomainSnapshotFree() on each array element, then calling * free() on @snaps. + * + * Since: v0.9.13 + * */ int virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot, @@ -706,6 +739,9 @@ virDomainSnapshotListAllChildren(virDomainSnapshotPtr snapshot, * Returns a domain snapshot object or NULL in case of failure. If the * domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT * error is raised. + * + * Since: v0.8.0 + * */ virDomainSnapshotPtr virDomainSnapshotLookupByName(virDomainPtr domain, @@ -746,6 +782,9 @@ virDomainSnapshotLookupByName(virDomainPtr domain, * Determine if the domain has a current snapshot. * * Returns 1 if such snapshot exists, 0 if it doesn't, -1 on error. + * + * Since: v0.8.0 + * */ int virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags) @@ -786,6 +825,9 @@ virDomainHasCurrentSnapshot(virDomainPtr domain, unsigned int flags) * Returns a domain snapshot object or NULL in case of failure. If the * current domain snapshot cannot be found, then the VIR_ERR_NO_DOMAIN_SNAPSHOT * error is raised. + * + * Since: v0.8.0 + * */ virDomainSnapshotPtr virDomainSnapshotCurrent(virDomainPtr domain, @@ -828,6 +870,9 @@ virDomainSnapshotCurrent(virDomainPtr domain, * Returns a domain snapshot object or NULL in case of failure. If the * given snapshot is a root (no parent), then the VIR_ERR_NO_DOMAIN_SNAPSHOT * error is raised. + * + * Since: v0.9.7 + * */ virDomainSnapshotPtr virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot, @@ -866,6 +911,9 @@ virDomainSnapshotGetParent(virDomainSnapshotPtr snapshot, * also virDomainHasCurrentSnapshot(). * * Returns 1 if current, 0 if not current, or -1 on error. + * + * Since: v0.9.13 + * */ int virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot, @@ -905,6 +953,9 @@ virDomainSnapshotIsCurrent(virDomainSnapshotPtr snapshot, * * Returns 1 if the snapshot has metadata, 0 if the snapshot exists without * help from libvirt, or -1 on error. + * + * Since: v0.9.13 + * */ int virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot, @@ -984,6 +1035,9 @@ virDomainSnapshotHasMetadata(virDomainSnapshotPtr snapshot, * NVRAM from the pristine template. * * Returns 0 if the creation is successful, -1 on error. + * + * Since: v0.8.0 + * */ int virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot, @@ -1041,6 +1095,9 @@ virDomainRevertToSnapshot(virDomainSnapshotPtr snapshot, * * Returns 0 if the selected snapshot(s) were successfully deleted, * -1 on error. + * + * Since: v0.8.0 + * */ int virDomainSnapshotDelete(virDomainSnapshotPtr snapshot, @@ -1091,6 +1148,9 @@ virDomainSnapshotDelete(virDomainSnapshotPtr snapshot, * increment the reference count. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.13 + * */ int virDomainSnapshotRef(virDomainSnapshotPtr snapshot) @@ -1114,6 +1174,9 @@ virDomainSnapshotRef(virDomainSnapshotPtr snapshot) * The data structure is freed and should not be used thereafter. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.8.0 + * */ int virDomainSnapshotFree(virDomainSnapshotPtr snapshot) diff --git a/src/libvirt-domain.c b/src/libvirt-domain.c index cbd7902d2d..cb7fa7471b 100644 --- a/src/libvirt-domain.c +++ b/src/libvirt-domain.c @@ -49,6 +49,9 @@ VIR_LOG_INIT("libvirt.domain"); * call to virConnectNumOfDomains() and this call; you are only guaranteed * that all currently active domains were listed if the return is less * than @maxids. + * + * Since: v0.0.1 + * */ int virConnectListDomains(virConnectPtr conn, int *ids, int maxids) @@ -82,6 +85,9 @@ virConnectListDomains(virConnectPtr conn, int *ids, int maxids) * Provides the number of active domains. * * Returns the number of domain found or -1 in case of error + * + * Since: v0.0.1 + * */ int virConnectNumOfDomains(virConnectPtr conn) @@ -115,6 +121,9 @@ virConnectNumOfDomains(virConnectPtr conn) * call. * * Returns the virConnectPtr or NULL in case of failure. + * + * Since: v0.3.0 + * */ virConnectPtr virDomainGetConnect(virDomainPtr dom) @@ -162,6 +171,9 @@ virDomainGetConnect(virDomainPtr dom) * domain object is no longer needed. * * Returns a new domain object or NULL in case of failure + * + * Since: v0.5.0 + * */ virDomainPtr virDomainCreateXML(virConnectPtr conn, const char *xmlDesc, @@ -228,6 +240,9 @@ virDomainCreateXML(virConnectPtr conn, const char *xmlDesc, * domain object is no longer needed. * * Returns a new domain object or NULL in case of failure + * + * Since: v1.1.1 + * */ virDomainPtr virDomainCreateXMLWithFiles(virConnectPtr conn, const char *xmlDesc, @@ -284,6 +299,9 @@ virDomainCreateXMLWithFiles(virConnectPtr conn, const char *xmlDesc, * This existing name will be left indefinitely for API compatibility. * * Returns a new domain object or NULL in case of failure + * + * Since: v0.0.1 + * */ virDomainPtr virDomainCreateLinux(virConnectPtr conn, const char *xmlDesc, @@ -307,6 +325,9 @@ virDomainCreateLinux(virConnectPtr conn, const char *xmlDesc, * * Returns a new domain object or NULL in case of failure. If the * domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised. + * + * Since: v0.0.1 + * */ virDomainPtr virDomainLookupByID(virConnectPtr conn, int id) @@ -346,6 +367,9 @@ virDomainLookupByID(virConnectPtr conn, int id) * * Returns a new domain object or NULL in case of failure. If the * domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised. + * + * Since: v0.0.5 + * */ virDomainPtr virDomainLookupByUUID(virConnectPtr conn, const unsigned char *uuid) @@ -385,6 +409,9 @@ virDomainLookupByUUID(virConnectPtr conn, const unsigned char *uuid) * * Returns a new domain object or NULL in case of failure. If the * domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised. + * + * Since: v0.1.1 + * */ virDomainPtr virDomainLookupByUUIDString(virConnectPtr conn, const char *uuidstr) @@ -422,6 +449,9 @@ virDomainLookupByUUIDString(virConnectPtr conn, const char *uuidstr) * * Returns a new domain object or NULL in case of failure. If the * domain cannot be found, then VIR_ERR_NO_DOMAIN error is raised. + * + * Since: v0.0.1 + * */ virDomainPtr virDomainLookupByName(virConnectPtr conn, const char *name) @@ -472,6 +502,9 @@ virDomainLookupByName(virConnectPtr conn, const char *name) * be deleted when the domain quits. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.0.1 + * */ int virDomainDestroy(virDomainPtr domain) @@ -537,6 +570,9 @@ virDomainDestroy(virDomainPtr domain) * * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.4 + * */ int virDomainDestroyFlags(virDomainPtr domain, @@ -577,6 +613,9 @@ virDomainDestroyFlags(virDomainPtr domain, * The data structure is freed and should not be used thereafter. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.0.1 + * */ int virDomainFree(virDomainPtr domain) @@ -608,6 +647,9 @@ virDomainFree(virDomainPtr domain) * the reference count. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.6.0 + * */ int virDomainRef(virDomainPtr domain) @@ -636,6 +678,9 @@ virDomainRef(virDomainPtr domain) * special state like VIR_DOMAIN_PMSUSPENDED. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.0.1 + * */ int virDomainSuspend(virDomainPtr domain) @@ -678,6 +723,9 @@ virDomainSuspend(virDomainPtr domain) * special state like VIR_DOMAIN_PMSUSPENDED. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.0.1 + * */ int virDomainResume(virDomainPtr domain) @@ -734,6 +782,9 @@ virDomainResume(virDomainPtr domain) * * Returns: 0 on success, * -1 on failure. + * + * Since: v0.9.10 + * */ int virDomainPMSuspendForDuration(virDomainPtr dom, @@ -781,6 +832,9 @@ virDomainPMSuspendForDuration(virDomainPtr dom, * * Returns: 0 on success, * -1 on failure. + * + * Since: v0.9.11 + * */ int virDomainPMWakeup(virDomainPtr dom, @@ -828,6 +882,9 @@ virDomainPMWakeup(virDomainPtr dom, * and virDomainSaveImageDefineXML(). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.0.2 + * */ int virDomainSave(virDomainPtr domain, const char *to) @@ -910,6 +967,9 @@ virDomainSave(virDomainPtr domain, const char *to) * to stop the block job first. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.4 + * */ int virDomainSaveFlags(virDomainPtr domain, const char *to, @@ -970,6 +1030,9 @@ virDomainSaveFlags(virDomainPtr domain, const char *to, * See virDomainRestoreFlags() for more control. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.0.2 + * */ int virDomainRestore(virConnectPtr conn, const char *from) @@ -1042,6 +1105,9 @@ virDomainRestore(virConnectPtr conn, const char *from) * pristine template. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.4 + * */ int virDomainRestoreFlags(virConnectPtr conn, const char *from, const char *dxml, @@ -1104,6 +1170,9 @@ virDomainRestoreFlags(virConnectPtr conn, const char *from, const char *dxml, * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of * error. The caller must free() the returned value. + * + * Since: v0.9.4 + * */ char * virDomainSaveImageGetXMLDesc(virConnectPtr conn, const char *file, @@ -1172,6 +1241,9 @@ virDomainSaveImageGetXMLDesc(virConnectPtr conn, const char *file, * exclusive. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.4 + * */ int virDomainSaveImageDefineXML(virConnectPtr conn, const char *file, @@ -1246,6 +1318,9 @@ virDomainSaveImageDefineXML(virConnectPtr conn, const char *file, * For more control over the output format, see virDomainCoreDumpWithFormat(). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.1.9 + * */ int virDomainCoreDump(virDomainPtr domain, const char *to, unsigned int flags) @@ -1322,6 +1397,9 @@ virDomainCoreDump(virDomainPtr domain, const char *to, unsigned int flags) * pressure on file system cache, but also risks slowing saves to NFS. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.2.3 + * */ int virDomainCoreDumpWithFormat(virDomainPtr domain, const char *to, @@ -1401,6 +1479,9 @@ virDomainCoreDumpWithFormat(virDomainPtr domain, const char *to, * * Returns a string representing the mime-type of the image format, or * NULL upon error. The caller must free() the returned value. + * + * Since: v0.9.2 + * */ char * virDomainScreenshot(virDomainPtr domain, @@ -1460,6 +1541,9 @@ virDomainScreenshot(virDomainPtr domain, * be deleted when the domain quits. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.0.1 + * */ int virDomainShutdown(virDomainPtr domain) @@ -1520,6 +1604,9 @@ virDomainShutdown(virDomainPtr domain) * must have <channel> configured. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.10 + * */ int virDomainShutdownFlags(virDomainPtr domain, unsigned int flags) @@ -1578,6 +1665,9 @@ virDomainShutdownFlags(virDomainPtr domain, unsigned int flags) * to a plain shutdown on the destination. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.1.0 + * */ int virDomainReboot(virDomainPtr domain, unsigned int flags) @@ -1622,6 +1712,9 @@ virDomainReboot(virDomainPtr domain, unsigned int flags) * guest OS shutdown. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.7 + * */ int virDomainReset(virDomainPtr domain, unsigned int flags) @@ -1661,6 +1754,9 @@ virDomainReset(virDomainPtr domain, unsigned int flags) * * Returns a pointer to the name or NULL, the string need not be deallocated * its lifetime will be the same as the domain object. + * + * Since: v0.0.1 + * */ const char * virDomainGetName(virDomainPtr domain) @@ -1683,6 +1779,9 @@ virDomainGetName(virDomainPtr domain) * Get the UUID for a domain * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.0.5 + * */ int virDomainGetUUID(virDomainPtr domain, unsigned char *uuid) @@ -1713,6 +1812,9 @@ virDomainGetUUID(virDomainPtr domain, unsigned char *uuid) * UUID see RFC4122. * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.1.1 + * */ int virDomainGetUUIDString(virDomainPtr domain, char *buf) @@ -1740,6 +1842,9 @@ virDomainGetUUIDString(virDomainPtr domain, char *buf) * Get the hypervisor ID number for the domain * * Returns the domain ID number or (unsigned int) -1 in case of error + * + * Since: v0.0.1 + * */ unsigned int virDomainGetID(virDomainPtr domain) @@ -1762,6 +1867,9 @@ virDomainGetID(virDomainPtr domain) * * Returns the new string or NULL in case of error, the string must be * freed by the caller. + * + * Since: v0.0.1 + * */ char * virDomainGetOSType(virDomainPtr domain) @@ -1801,6 +1909,9 @@ virDomainGetOSType(virDomainPtr domain) * * Returns the memory size in kibibytes (blocks of 1024 bytes), or 0 in * case of error. + * + * Since: v0.0.1 + * */ unsigned long virDomainGetMaxMemory(virDomainPtr domain) @@ -1850,6 +1961,9 @@ virDomainGetMaxMemory(virDomainPtr domain) * virDomainSetMemoryFlags(). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.0.1 + * */ int virDomainSetMaxMemory(virDomainPtr domain, unsigned long memory) @@ -1903,6 +2017,9 @@ virDomainSetMaxMemory(virDomainPtr domain, unsigned long memory) * virDomainSetMemoryFlags(). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.1.1 + * */ int virDomainSetMemory(virDomainPtr domain, unsigned long memory) @@ -1965,6 +2082,9 @@ virDomainSetMemory(virDomainPtr domain, unsigned long memory) * Not all hypervisors can support all flag combinations. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.9.0 + * */ int virDomainSetMemoryFlags(virDomainPtr domain, unsigned long memory, @@ -2025,6 +2145,9 @@ virDomainSetMemoryFlags(virDomainPtr domain, unsigned long memory, * Not all hypervisors can support all flag combinations. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.1.1 + * */ int virDomainSetMemoryStatsPeriod(virDomainPtr domain, int period, @@ -2075,6 +2198,9 @@ virDomainSetMemoryStatsPeriod(virDomainPtr domain, int period, * VIR_DOMAIN_MEMORY_PARAM_UNLIMITED. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.8.5 + * */ int virDomainSetMemoryParameters(virDomainPtr domain, @@ -2149,6 +2275,9 @@ virDomainSetMemoryParameters(virDomainPtr domain, * expects the caller to allocate the @params. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.8.5 + * */ int virDomainGetMemoryParameters(virDomainPtr domain, @@ -2216,6 +2345,9 @@ virDomainGetMemoryParameters(virDomainPtr domain, * Changing persistent configuration does not pose such limitations. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.9 + * */ int virDomainSetNumaParameters(virDomainPtr domain, @@ -2281,6 +2413,9 @@ virDomainSetNumaParameters(virDomainPtr domain, * expects the caller to allocate the @params. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.9 + * */ int virDomainGetNumaParameters(virDomainPtr domain, @@ -2338,6 +2473,9 @@ virDomainGetNumaParameters(virDomainPtr domain, * This function may require privileged access to the hypervisor. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.0 + * */ int virDomainSetBlkioParameters(virDomainPtr domain, @@ -2403,6 +2541,9 @@ virDomainSetBlkioParameters(virDomainPtr domain, * expects the caller to allocate the @params. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.0 + * */ int virDomainGetBlkioParameters(virDomainPtr domain, @@ -2461,6 +2602,9 @@ virDomainGetBlkioParameters(virDomainPtr domain, * can be extracted. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.0.1 + * */ int virDomainGetInfo(virDomainPtr domain, virDomainInfoPtr info) @@ -2507,6 +2651,9 @@ virDomainGetInfo(virDomainPtr domain, virDomainInfoPtr info) * which led to the state. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.2 + * */ int virDomainGetState(virDomainPtr domain, @@ -2550,6 +2697,9 @@ virDomainGetState(virDomainPtr domain, * Extract details about current state of control interface to a domain. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.3 + * */ int virDomainGetControlInfo(virDomainPtr domain, @@ -2611,6 +2761,9 @@ virDomainGetControlInfo(virDomainPtr domain, * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case * of error. The caller must free() the returned value. + * + * Since: v0.0.1 + * */ char * virDomainGetXMLDesc(virDomainPtr domain, unsigned int flags) @@ -2660,6 +2813,9 @@ virDomainGetXMLDesc(virDomainPtr domain, unsigned int flags) * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case * of error. The caller must free() the returned value. + * + * Since: v0.6.4 + * */ char * virConnectDomainXMLFromNative(virConnectPtr conn, @@ -2710,6 +2866,9 @@ virConnectDomainXMLFromNative(virConnectPtr conn, * * Returns a 0 terminated UTF-8 encoded native config datafile, or * NULL in case of error. The caller must free() the returned value. + * + * Since: v0.6.4 + * */ char * virConnectDomainXMLToNative(virConnectPtr conn, @@ -3563,6 +3722,9 @@ virDomainMigrateUnmanaged(virDomainPtr domain, * Returns the new domain object if the migration was successful, * or NULL in case of error. Note that the new domain object * exists in the scope of the destination connection (dconn). + * + * Since: v0.3.2 + * */ virDomainPtr virDomainMigrate(virDomainPtr domain, @@ -3759,6 +3921,9 @@ virDomainMigrate(virDomainPtr domain, * Returns the new domain object if the migration was successful, * or NULL in case of error. Note that the new domain object * exists in the scope of the destination connection (dconn). + * + * Since: v0.9.2 + * */ virDomainPtr virDomainMigrate2(virDomainPtr domain, @@ -3968,6 +4133,9 @@ virDomainMigrate2(virDomainPtr domain, * Returns the new domain object if the migration was successful, * or NULL in case of error. Note that the new domain object * exists in the scope of the destination connection (dconn). + * + * Since: v1.1.0 + * */ virDomainPtr virDomainMigrate3(virDomainPtr domain, @@ -4256,6 +4424,9 @@ int virDomainMigrateUnmanagedCheckCompat(virDomainPtr domain, * corresponds to VIR_MIGRATE_PARAM_URI of virDomainMigrateToURI3. * * Returns 0 if the migration succeeded, -1 upon error. + * + * Since: v0.7.2 + * */ int virDomainMigrateToURI(virDomainPtr domain, @@ -4332,6 +4503,9 @@ virDomainMigrateToURI(virDomainPtr domain, * virDomainMigrateToURI3. * * Returns 0 if the migration succeeded, -1 upon error. + * + * Since: v0.9.2 + * */ int virDomainMigrateToURI2(virDomainPtr domain, @@ -4412,6 +4586,9 @@ virDomainMigrateToURI2(virDomainPtr domain, * different types of hypervisor. * * Returns 0 if the migration succeeded, -1 upon error. + * + * Since: v1.1.0 + * */ int virDomainMigrateToURI3(virDomainPtr domain, @@ -5281,6 +5458,9 @@ virDomainMigrateConfirm3Params(virDomainPtr domain, * Get the scheduler type and the number of scheduler parameters. * * Returns NULL in case of error. The caller must free the returned string. + * + * Since: v0.2.3 + * */ char * virDomainGetSchedulerType(virDomainPtr domain, int *nparams) @@ -5329,6 +5509,9 @@ virDomainGetSchedulerType(virDomainPtr domain, int *nparams) * virDomainGetSchedulerParametersFlags(). * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.2.3 + * */ int virDomainGetSchedulerParameters(virDomainPtr domain, @@ -5394,6 +5577,9 @@ virDomainGetSchedulerParameters(virDomainPtr domain, * } * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.2 + * */ int virDomainGetSchedulerParametersFlags(virDomainPtr domain, @@ -5458,6 +5644,9 @@ virDomainGetSchedulerParametersFlags(virDomainPtr domain, * virDomainSetSchedulerParametersFlags. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.2.3 + * */ int virDomainSetSchedulerParameters(virDomainPtr domain, @@ -5512,6 +5701,9 @@ virDomainSetSchedulerParameters(virDomainPtr domain, * flags are supported. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.2 + * */ int virDomainSetSchedulerParametersFlags(virDomainPtr domain, @@ -5583,6 +5775,9 @@ virDomainSetSchedulerParametersFlags(virDomainPtr domain, * that particular statistic. * * Returns: 0 in case of success or -1 in case of failure. + * + * Since: v0.3.2 + * */ int virDomainBlockStats(virDomainPtr dom, const char *disk, @@ -5660,6 +5855,9 @@ virDomainBlockStats(virDomainPtr dom, const char *disk, * again. See virDomainGetMemoryParameters() for more details. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.5 + * */ int virDomainBlockStatsFlags(virDomainPtr dom, @@ -5729,6 +5927,9 @@ virDomainBlockStatsFlags(virDomainPtr dom, * The returned stats are from domain's point of view. * * Returns: 0 in case of success or -1 in case of failure. + * + * Since: v0.3.2 + * */ int virDomainInterfaceStats(virDomainPtr dom, const char *device, @@ -5789,6 +5990,9 @@ virDomainInterfaceStats(virDomainPtr dom, const char *device, * This function may require privileged access to the hypervisor. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.9 + * */ int virDomainSetInterfaceParameters(virDomainPtr domain, @@ -5857,6 +6061,9 @@ virDomainSetInterfaceParameters(virDomainPtr domain, * expects the caller to allocate the @params. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.9 + * */ int virDomainGetInterfaceParameters(virDomainPtr domain, @@ -5947,6 +6154,9 @@ virDomainGetInterfaceParameters(virDomainPtr domain, * The number of failed huge page allocations from inside the domain * * Returns: The number of stats provided or -1 in case of failure. + * + * Since: v0.7.5 + * */ int virDomainMemoryStats(virDomainPtr dom, virDomainMemoryStatPtr stats, @@ -6026,6 +6236,9 @@ virDomainMemoryStats(virDomainPtr dom, virDomainMemoryStatPtr stats, * Now large requests up to 16M byte are supported. * * Returns: 0 in case of success or -1 in case of failure. + * + * Since: v0.4.4 + * */ int virDomainBlockPeek(virDomainPtr dom, @@ -6095,6 +6308,9 @@ virDomainBlockPeek(virDomainPtr dom, * hypervisor. * * Returns: 0 in case of success or -1 in case of failure. + * + * Since: v0.9.8 + * */ int virDomainBlockResize(virDomainPtr dom, @@ -6163,6 +6379,9 @@ virDomainBlockResize(virDomainPtr dom, * Now large requests up to 16M byte are supported. * * Returns: 0 in case of success or -1 in case of failure. + * + * Since: v0.4.4 + * */ int virDomainMemoryPeek(virDomainPtr dom, @@ -6299,6 +6518,9 @@ virDomainMemoryPeek(virDomainPtr dom, * ... * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.8.1 + * */ int virDomainGetBlockInfo(virDomainPtr domain, const char *disk, @@ -6349,6 +6571,9 @@ virDomainGetBlockInfo(virDomainPtr domain, const char *disk, * domain object is no longer needed. * * Returns NULL in case of error, a pointer to the domain otherwise + * + * Since: v0.1.1 + * */ virDomainPtr virDomainDefineXML(virConnectPtr conn, const char *xml) @@ -6392,6 +6617,9 @@ virDomainDefineXML(virConnectPtr conn, const char *xml) * domain object is no longer needed. * * Returns NULL in case of error, a pointer to the domain otherwise + * + * Since: v1.2.12 + * */ virDomainPtr virDomainDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags) @@ -6435,6 +6663,9 @@ virDomainDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags) * will fail. See virDomainUndefineFlags() for more control. * * Returns 0 in case of success, -1 in case of error + * + * Since: v0.1.1 + * */ int virDomainUndefine(virDomainPtr domain) @@ -6504,6 +6735,9 @@ virDomainUndefine(virDomainPtr domain) * VIR_DOMAIN_UNDEFINE_NVRAM is specified to remove the nvram file. * * Returns 0 in case of success, -1 in case of error + * + * Since: v0.9.4 + * */ int virDomainUndefineFlags(virDomainPtr domain, @@ -6543,6 +6777,9 @@ virDomainUndefineFlags(virDomainPtr domain, * Provides the number of defined but inactive domains. * * Returns the number of domain found or -1 in case of error + * + * Since: v0.1.6 + * */ int virConnectNumOfDefinedDomains(virConnectPtr conn) @@ -6586,6 +6823,9 @@ virConnectNumOfDefinedDomains(virConnectPtr conn) * a call to virConnectNumOfDefinedDomains() and this call; you are only * guaranteed that all currently defined domains were listed if the return * is less than @maxids. The client must call free() on each returned name. + * + * Since: v0.1.1 + * */ int virConnectListDefinedDomains(virConnectPtr conn, char **const names, @@ -6685,6 +6925,9 @@ virConnectListDefinedDomains(virConnectPtr conn, char **const names, * extra allocated element set to NULL but not included in the return count, to * make iteration easier. The caller is responsible for calling virDomainFree() * on each array element, then calling free() on @domains. + * + * Since: v0.9.13 + * */ int virConnectListAllDomains(virConnectPtr conn, @@ -6726,6 +6969,9 @@ virConnectListAllDomains(virConnectPtr conn, * control, see virDomainCreateWithFlags(). * * Returns 0 in case of success, -1 in case of error + * + * Since: v0.1.1 + * */ int virDomainCreate(virDomainPtr domain) @@ -6794,6 +7040,9 @@ virDomainCreate(virDomainPtr domain) * pristine template. * * Returns 0 in case of success, -1 in case of error + * + * Since: v0.8.2 + * */ int virDomainCreateWithFlags(virDomainPtr domain, unsigned int flags) @@ -6870,6 +7119,9 @@ virDomainCreateWithFlags(virDomainPtr domain, unsigned int flags) * pristine template. * * Returns 0 in case of success, -1 in case of error + * + * Since: v1.1.1 + * */ int virDomainCreateWithFiles(virDomainPtr domain, unsigned int nfiles, @@ -6927,6 +7179,9 @@ virDomainCreateWithFiles(virDomainPtr domain, unsigned int nfiles, * machine boots. * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.2.1 + * */ int virDomainGetAutostart(virDomainPtr domain, @@ -6968,6 +7223,9 @@ virDomainGetAutostart(virDomainPtr domain, * when the host machine boots. * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.2.1 + * */ int virDomainSetAutostart(virDomainPtr domain, @@ -7008,6 +7266,9 @@ virDomainSetAutostart(virDomainPtr domain, * Send NMI to the guest * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.9.2 + * */ int virDomainInjectNMI(virDomainPtr domain, unsigned int flags) @@ -7050,6 +7311,9 @@ virDomainInjectNMI(virDomainPtr domain, unsigned int flags) * Send key(s) to the guest. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.9.3 + * */ int virDomainSendKey(virDomainPtr domain, @@ -7135,6 +7399,9 @@ virDomainSendKey(virDomainPtr domain, * the container/guest. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.1 + * */ int virDomainSendProcessSignal(virDomainPtr domain, @@ -7192,6 +7459,9 @@ virDomainSendProcessSignal(virDomainPtr domain, * use virDomainSetVcpusFlags(). * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.1.4 + * */ int virDomainSetVcpus(virDomainPtr domain, unsigned int nvcpus) @@ -7263,6 +7533,9 @@ virDomainSetVcpus(virDomainPtr domain, unsigned int nvcpus) * Not all hypervisors can support all flag combinations. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.8.5 + * */ int virDomainSetVcpusFlags(virDomainPtr domain, unsigned int nvcpus, @@ -7332,6 +7605,9 @@ virDomainSetVcpusFlags(virDomainPtr domain, unsigned int nvcpus, * on live domains. Guest agent may be needed for this flag to be available. * * Returns the number of vCPUs in case of success, -1 in case of failure. + * + * Since: v0.8.5 + * */ int virDomainGetVcpusFlags(virDomainPtr domain, unsigned int flags) @@ -7388,6 +7664,9 @@ virDomainGetVcpusFlags(virDomainPtr domain, unsigned int flags) * so can only be called on an active domain. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.1.4 + * */ int virDomainPinVcpu(virDomainPtr domain, unsigned int vcpu, @@ -7455,6 +7734,9 @@ virDomainPinVcpu(virDomainPtr domain, unsigned int vcpu, * * Returns 0 in case of success, -1 in case of failure. * + * Since: v0.9.3 + * + * */ int virDomainPinVcpuFlags(virDomainPtr domain, unsigned int vcpu, @@ -7513,6 +7795,9 @@ virDomainPinVcpuFlags(virDomainPtr domain, unsigned int vcpu, * * Returns the number of virtual CPUs in case of success, * -1 in case of failure. + * + * Since: v0.9.3 + * */ int virDomainGetVcpuPinInfo(virDomainPtr domain, int ncpumaps, @@ -7590,6 +7875,9 @@ virDomainGetVcpuPinInfo(virDomainPtr domain, int ncpumaps, * * Returns 0 in case of success, -1 in case of failure. * + * Since: v0.10.0 + * + * */ int virDomainPinEmulator(virDomainPtr domain, unsigned char *cpumap, @@ -7645,6 +7933,9 @@ virDomainPinEmulator(virDomainPtr domain, unsigned char *cpumap, * Returns 1 in case of success, * 0 in case of no emulator threads are pined to pcpus, * -1 in case of failure. + * + * Since: v0.10.0 + * */ int virDomainGetEmulatorPinInfo(virDomainPtr domain, unsigned char *cpumap, @@ -7710,6 +8001,9 @@ virDomainGetEmulatorPinInfo(virDomainPtr domain, unsigned char *cpumap, * an inactive domain. * * Returns the number of info filled in case of success, -1 in case of failure. + * + * Since: v0.1.4 + * */ int virDomainGetVcpus(virDomainPtr domain, virVcpuInfoPtr info, int maxinfo, @@ -7769,6 +8063,9 @@ virDomainGetVcpus(virDomainPtr domain, virVcpuInfoPtr info, int maxinfo, * guest was booted with. For more details, see virDomainGetVcpusFlags(). * * Returns the maximum of virtual CPU or -1 in case of error. + * + * Since: v0.2.1 + * */ int virDomainGetMaxVcpus(virDomainPtr domain) @@ -7813,6 +8110,9 @@ virDomainGetMaxVcpus(virDomainPtr domain) * On success, the array of information is stored into @info. The caller is * responsible for calling virDomainIOThreadInfoFree() on each array element, * then calling free() on @info. On error, @info is set to NULL. + * + * Since: v1.2.14 + * */ int virDomainGetIOThreadInfo(virDomainPtr dom, @@ -7852,6 +8152,9 @@ virDomainGetIOThreadInfo(virDomainPtr dom, * @info: pointer to a virDomainIOThreadInfo object * * Frees the memory used by @info. + * + * Since: v1.2.14 + * */ void virDomainIOThreadInfoFree(virDomainIOThreadInfoPtr info) @@ -7895,6 +8198,9 @@ virDomainIOThreadInfoFree(virDomainIOThreadInfoPtr info) * See also virDomainGetIOThreadInfo for querying this information. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.2.14 + * */ int virDomainPinIOThread(virDomainPtr domain, @@ -7959,6 +8265,9 @@ virDomainPinIOThread(virDomainPtr domain, * just live or both live and persistent state is changed. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.2.15 + * */ int virDomainAddIOThread(virDomainPtr domain, @@ -8018,6 +8327,9 @@ virDomainAddIOThread(virDomainPtr domain, * just live or both live and persistent state is changed. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.2.15 + * */ int virDomainDelIOThread(virDomainPtr domain, @@ -8079,6 +8391,9 @@ virDomainDelIOThread(virDomainPtr domain, * This function requires privileged access to the hypervisor. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v4.10.0 + * */ int virDomainSetIOThreadParams(virDomainPtr domain, @@ -8132,6 +8447,9 @@ virDomainSetIOThreadParams(virDomainPtr domain, * string if the domain is not running under a security model. * * Returns 0 in case of success, -1 in case of failure + * + * Since: v0.6.1 + * */ int virDomainGetSecurityLabel(virDomainPtr domain, virSecurityLabelPtr seclabel) @@ -8174,6 +8492,9 @@ virDomainGetSecurityLabel(virDomainPtr domain, virSecurityLabelPtr seclabel) * string if the domain is not running under a security model. * * Returns number of elements in @seclabels on success, -1 in case of failure. + * + * Since: v0.10.0 + * */ int virDomainGetSecurityLabelList(virDomainPtr domain, @@ -8236,6 +8557,9 @@ virDomainGetSecurityLabelList(virDomainPtr domain, * or both will be modified. * * Returns 0 on success, -1 in case of failure. + * + * Since: v0.9.10 + * */ int virDomainSetMetadata(virDomainPtr domain, @@ -8321,6 +8645,9 @@ virDomainSetMetadata(virDomainPtr domain, * * Returns the metadata string on success (caller must free), * or NULL in case of failure. + * + * Since: v0.9.10 + * */ char * virDomainGetMetadata(virDomainPtr domain, @@ -8388,6 +8715,9 @@ virDomainGetMetadata(virDomainPtr domain, * persistent domain definition. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.1.9 + * */ int virDomainAttachDevice(virDomainPtr domain, const char *xml) @@ -8447,6 +8777,9 @@ virDomainAttachDevice(virDomainPtr domain, const char *xml) * persistent domain definition. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.7.7 + * */ int virDomainAttachDeviceFlags(virDomainPtr domain, @@ -8491,6 +8824,9 @@ virDomainAttachDeviceFlags(virDomainPtr domain, * See virDomainDetachDeviceFlags() for more details. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.1.9 + * */ int virDomainDetachDevice(virDomainPtr domain, const char *xml) @@ -8573,6 +8909,9 @@ virDomainDetachDevice(virDomainPtr domain, const char *xml) * may lead to unexpected results. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.7.7 + * */ int virDomainDetachDeviceFlags(virDomainPtr domain, @@ -8637,6 +8976,9 @@ virDomainDetachDeviceFlags(virDomainPtr domain, * domain XML with only the disk path changed. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.8.0 + * */ int virDomainUpdateDeviceFlags(virDomainPtr domain, @@ -8691,6 +9033,9 @@ virDomainUpdateDeviceFlags(virDomainPtr domain, * device removal. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v4.4.0 + * */ int virDomainDetachDeviceAlias(virDomainPtr domain, @@ -8751,6 +9096,9 @@ virDomainDetachDeviceAlias(virDomainPtr domain, * Returns 0 on success, -1 on failure. Older versions of some hypervisors * sometimes returned a positive number on success, but without any reliable * semantics on what that number represents. + * + * Since: v0.5.0 + * */ int virConnectDomainEventRegister(virConnectPtr conn, @@ -8794,6 +9142,9 @@ virConnectDomainEventRegister(virConnectPtr conn, * Returns 0 on success, -1 on failure. Older versions of some hypervisors * sometimes returned a positive number on success, but without any reliable * semantics on what that number represents. + * + * Since: v0.5.0 + * */ int virConnectDomainEventDeregister(virConnectPtr conn, @@ -8828,6 +9179,9 @@ virConnectDomainEventDeregister(virConnectPtr conn, * Determine if the domain is currently running * * Returns 1 if running, 0 if inactive, -1 on error + * + * Since: v0.7.3 + * */ int virDomainIsActive(virDomainPtr dom) @@ -8861,6 +9215,9 @@ virDomainIsActive(virDomainPtr dom) * which means it will still exist after shutting down * * Returns 1 if persistent, 0 if transient, -1 on error + * + * Since: v0.7.3 + * */ int virDomainIsPersistent(virDomainPtr dom) @@ -8901,6 +9258,9 @@ virDomainIsPersistent(virDomainPtr dom) * advised to change these after the rename was successful. * * Returns 0 if successfully renamed, -1 on error + * + * Since: v1.2.19 + * */ int virDomainRename(virDomainPtr dom, @@ -8934,6 +9294,9 @@ virDomainRename(virDomainPtr dom, * Determine if the domain has been updated. * * Returns 1 if updated, 0 if not, -1 on error + * + * Since: v0.8.6 + * */ int virDomainIsUpdated(virDomainPtr dom) @@ -8971,6 +9334,9 @@ virDomainIsUpdated(virDomainPtr dom) * to virDomainGetJobStats(). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.7.7 + * */ int virDomainGetJobInfo(virDomainPtr domain, virDomainJobInfoPtr info) @@ -9035,6 +9401,9 @@ virDomainGetJobInfo(virDomainPtr domain, virDomainJobInfoPtr info) * source host in case of a migration job). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v1.0.3 + * */ int virDomainGetJobStats(virDomainPtr domain, @@ -9087,6 +9456,9 @@ virDomainGetJobStats(virDomainPtr domain, * for more details). * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.7.7 + * */ int virDomainAbortJob(virDomainPtr domain) @@ -9129,6 +9501,9 @@ virDomainAbortJob(virDomainPtr domain) * being live-migrated as a reaction to migration progress. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v0.8.0 + * */ int virDomainMigrateSetMaxDowntime(virDomainPtr domain, @@ -9170,6 +9545,9 @@ virDomainMigrateSetMaxDowntime(virDomainPtr domain, * at the end of live migration. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v3.7.0 + * */ int virDomainMigrateGetMaxDowntime(virDomainPtr domain, @@ -9210,6 +9588,9 @@ virDomainMigrateGetMaxDowntime(virDomainPtr domain, * transferred memory pages during live migration. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v1.0.3 + * */ int virDomainMigrateGetCompressionCache(virDomainPtr domain, @@ -9254,6 +9635,9 @@ virDomainMigrateGetCompressionCache(virDomainPtr domain, * virDomainGetJobStats. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v1.0.3 + * */ int virDomainMigrateSetCompressionCache(virDomainPtr domain, @@ -9298,6 +9682,9 @@ virDomainMigrateSetCompressionCache(virDomainPtr domain, * phase of the migration. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v0.9.0 + * */ int virDomainMigrateSetMaxSpeed(virDomainPtr domain, @@ -9341,6 +9728,9 @@ virDomainMigrateSetMaxSpeed(virDomainPtr domain, * migration. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v0.9.5 + * */ int virDomainMigrateGetMaxSpeed(virDomainPtr domain, @@ -9434,6 +9824,9 @@ virDomainMigrateGetMaxSpeed(virDomainPtr domain, * migration and there's no domain to run virDomainGetJobStats on). * * Returns 0 in case of success, -1 otherwise. + * + * Since: v1.3.3 + * */ int virDomainMigrateStartPostCopy(virDomainPtr domain, @@ -9497,6 +9890,9 @@ virDomainMigrateStartPostCopy(virDomainPtr domain, * be passed to the virConnectDomainEventDeregisterAny() method. * * Returns a callback identifier on success, -1 on failure. + * + * Since: v0.8.0 + * */ int virConnectDomainEventRegisterAny(virConnectPtr conn, @@ -9555,7 +9951,10 @@ virConnectDomainEventRegisterAny(virConnectPtr conn, * * Returns 0 on success, -1 on failure. Older versions of some hypervisors * sometimes returned a positive number on success, but without any reliable - * semantics on what that number represents. */ + * semantics on what that number represents. + * + * Since: v0.8.0 + * */ int virConnectDomainEventDeregisterAny(virConnectPtr conn, int callbackID) @@ -9610,6 +10009,9 @@ virConnectDomainEventDeregisterAny(virConnectPtr conn, * flags are mutually exclusive. * * Returns 0 in case of success or -1 in case of failure + * + * Since: v0.8.0 + * */ int virDomainManagedSave(virDomainPtr dom, unsigned int flags) @@ -9657,6 +10059,9 @@ virDomainManagedSave(virDomainPtr dom, unsigned int flags) * * Returns 0 if no image is present, 1 if an image is present, and * -1 in case of error + * + * Since: v0.8.0 + * */ int virDomainHasManagedSaveImage(virDomainPtr dom, unsigned int flags) @@ -9695,6 +10100,9 @@ virDomainHasManagedSaveImage(virDomainPtr dom, unsigned int flags) * Remove any managed save image for this domain. * * Returns 0 in case of success, and -1 in case of error + * + * Since: v0.8.0 + * */ int virDomainManagedSaveRemove(virDomainPtr dom, unsigned int flags) @@ -9741,6 +10149,9 @@ virDomainManagedSaveRemove(virDomainPtr dom, unsigned int flags) * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of * error. The caller must free() the returned value. + * + * Since: v3.7.0 + * */ char * virDomainManagedSaveGetXMLDesc(virDomainPtr domain, unsigned int flags) @@ -9799,6 +10210,9 @@ virDomainManagedSaveGetXMLDesc(virDomainPtr domain, unsigned int flags) * exclusive. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v3.7.0 + * */ int virDomainManagedSaveDefineXML(virDomainPtr domain, const char *dxml, @@ -9864,6 +10278,9 @@ virDomainManagedSaveDefineXML(virDomainPtr domain, const char *dxml, * versions, it is up to the client to ensure mutual exclusion. * * Returns 0 if the console was opened, -1 on error + * + * Since: v0.8.6 + * */ int virDomainOpenConsole(virDomainPtr dom, @@ -9928,6 +10345,9 @@ virDomainOpenConsole(virDomainPtr dom, * other client prior to opening this channel. * * Returns 0 if the channel was opened, -1 on error + * + * Since: v1.0.2 + * */ int virDomainOpenChannel(virDomainPtr dom, @@ -9985,6 +10405,9 @@ virDomainOpenChannel(virDomainPtr dom, * Linux perf events are performance analyzing tool in Linux. * * Returns -1 in case of failure, 0 in case of success. + * + * Since: v1.3.3 + * */ int virDomainGetPerfEvents(virDomainPtr domain, virTypedParameterPtr *params, @@ -10035,6 +10458,9 @@ int virDomainGetPerfEvents(virDomainPtr domain, * Linux perf events are performance analyzing tool in Linux. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v1.3.3 + * */ int virDomainSetPerfEvents(virDomainPtr domain, virTypedParameterPtr params, @@ -10118,6 +10544,9 @@ int virDomainSetPerfEvents(virDomainPtr domain, * beginning of the first phase. * * Returns -1 in case of failure, 0 when successful. + * + * Since: v0.9.4 + * */ int virDomainBlockJobAbort(virDomainPtr dom, const char *disk, @@ -10195,6 +10624,9 @@ virDomainBlockJobAbort(virDomainPtr dom, const char *disk, * space required for the backup. * * Returns -1 in case of failure, 0 when nothing found, 1 when info was found. + * + * Since: v0.9.4 + * */ int virDomainGetBlockJobInfo(virDomainPtr dom, const char *disk, @@ -10258,6 +10690,9 @@ virDomainGetBlockJobInfo(virDomainPtr dom, const char *disk, * elements within //domain/devices/disk. * * Returns -1 in case of failure, 0 when successful. + * + * Since: v0.9.4 + * */ int virDomainBlockJobSetSpeed(virDomainPtr dom, const char *disk, @@ -10332,6 +10767,9 @@ virDomainBlockJobSetSpeed(virDomainPtr dom, const char *disk, * This is shorthand for virDomainBlockRebase() with a NULL base. * * Returns 0 if the operation has started, -1 on failure. + * + * Since: v0.9.4 + * */ int virDomainBlockPull(virDomainPtr dom, const char *disk, @@ -10476,6 +10914,9 @@ virDomainBlockPull(virDomainPtr dom, const char *disk, * to the source format or probed from the reused file. * * Returns 0 if the operation has started, -1 on failure. + * + * Since: v0.9.10 + * */ int virDomainBlockRebase(virDomainPtr dom, const char *disk, @@ -10606,6 +11047,9 @@ virDomainBlockRebase(virDomainPtr dom, const char *disk, * is not a local file, and the possibility of additional tuning parameters. * * Returns 0 if the operation has started, -1 on failure. + * + * Since: v1.2.8 + * */ int virDomainBlockCopy(virDomainPtr dom, const char *disk, @@ -10752,6 +11196,9 @@ virDomainBlockCopy(virDomainPtr dom, const char *disk, * virDomainGetBlockJobInfo(). * * Returns 0 if the operation has started, -1 on failure. + * + * Since: v0.10.2 + * */ int virDomainBlockCommit(virDomainPtr dom, const char *disk, @@ -10811,6 +11258,9 @@ virDomainBlockCommit(virDomainPtr dom, const char *disk, * to use this method over a TCP connection will always fail * * Returns 0 on success, -1 on failure + * + * Since: v0.9.7 + * */ int virDomainOpenGraphics(virDomainPtr dom, @@ -10891,6 +11341,9 @@ virDomainOpenGraphics(virDomainPtr dom, * to use this method over a TCP connection will always fail. * * Returns an fd on success, -1 on failure + * + * Since: v1.2.8 + * */ int virDomainOpenGraphicsFD(virDomainPtr dom, @@ -10952,6 +11405,9 @@ virDomainOpenGraphicsFD(virDomainPtr dom, * within //domain/devices/disk. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.8 + * */ int virDomainSetBlockIoTune(virDomainPtr dom, @@ -11027,6 +11483,9 @@ virDomainSetBlockIoTune(virDomainPtr dom, * unless @nparams is 0 on input. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.8 + * */ int virDomainGetBlockIoTune(virDomainPtr dom, @@ -11156,6 +11615,9 @@ virDomainGetBlockIoTune(virDomainPtr dom, * skipped elements if @nparams is too large, and tail elements if * @ncpus is too large). The caller is responsible for freeing any * returned string parameters. + * + * Since: v0.9.10 + * */ int virDomainGetCPUStats(virDomainPtr domain, @@ -11256,6 +11718,9 @@ virDomainGetCPUStats(virDomainPtr domain, * * Returns number of disks with errors filled in the @errors array or -1 on * error. + * + * Since: v0.9.10 + * */ int virDomainGetDiskErrors(virDomainPtr dom, @@ -11301,6 +11766,9 @@ virDomainGetDiskErrors(virDomainPtr dom, * * Returns the hostname which must be freed by the caller, or * NULL if there was an error. + * + * Since: v0.10.0 + * */ char * virDomainGetHostname(virDomainPtr domain, unsigned int flags) @@ -11350,6 +11818,9 @@ virDomainGetHostname(virDomainPtr domain, unsigned int flags) * If @minimum is not zero, the command may fail. * * Returns 0 on success, -1 otherwise. + * + * Since: v1.0.1 + * */ int virDomainFSTrim(virDomainPtr dom, @@ -11394,6 +11865,9 @@ virDomainFSTrim(virDomainPtr dom, * support mountpoints argument), @mountpoints may need to be NULL. * * Returns the number of frozen filesystems on success, -1 otherwise. + * + * Since: v1.2.5 + * */ int virDomainFSFreeze(virDomainPtr dom, @@ -11437,6 +11911,9 @@ virDomainFSFreeze(virDomainPtr dom, * In some drivers (e.g. QEMU driver), @mountpoints may need to be NULL. * * Returns the number of thawed filesystems on success, -1 otherwise. + * + * Since: v1.2.5 + * */ int virDomainFSThaw(virDomainPtr dom, @@ -11482,6 +11959,9 @@ virDomainFSThaw(virDomainPtr dom, * be configured and running in order to run this API. * * Returns 0 on success, -1 otherwise. + * + * Since: v1.2.5 + * */ int virDomainGetTime(virDomainPtr dom, @@ -11532,6 +12012,9 @@ virDomainGetTime(virDomainPtr dom, * be configured and running in order to be able to run this API. * * Returns 0 on success, -1 otherwise. + * + * Since: v1.2.5 + * */ int virDomainSetTime(virDomainPtr dom, @@ -11578,6 +12061,9 @@ virDomainSetTime(virDomainPtr dom, * be configured and running in order to be able to run this API. * * Returns 0 on success, -1 otherwise. + * + * Since: v1.2.16 + * */ int virDomainSetUserPassword(virDomainPtr dom, @@ -11628,6 +12114,9 @@ virDomainSetUserPassword(virDomainPtr dom, * * Returns NULL in case of error or an XML string * defining the capabilities. + * + * Since: v1.2.7 + * */ char * virConnectGetDomainCapabilities(virConnectPtr conn, @@ -12034,6 +12523,9 @@ virConnectGetDomainCapabilities(virConnectPtr conn, * Returns the count of returned statistics structures on success, -1 on error. * The requested data are returned in the @retStats parameter. The returned * array should be freed by the caller. See virDomainStatsRecordListFree. + * + * Since: v1.2.8 + * */ int virConnectGetAllDomainStats(virConnectPtr conn, @@ -12113,6 +12605,9 @@ virConnectGetAllDomainStats(virConnectPtr conn, * array should be freed by the caller. See virDomainStatsRecordListFree. * Note that the count of returned stats may be less than the domain count * provided via @doms. + * + * Since: v1.2.8 + * */ int virDomainListGetStats(virDomainPtr *doms, @@ -12180,6 +12675,9 @@ virDomainListGetStats(virDomainPtr *doms, * * Convenience function to free a list of domain stats returned by * virDomainListGetStats and virConnectGetAllDomainStats. + * + * Since: v1.2.8 + * */ void virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats) @@ -12212,6 +12710,9 @@ virDomainStatsRecordListFree(virDomainStatsRecordPtr *stats) * On success, the array of the information is stored into @info. The caller is * responsible for calling virDomainFSInfoFree() on each array element, then * calling free() on @info. On error, @info is set to NULL. + * + * Since: v1.2.11 + * */ int virDomainGetFSInfo(virDomainPtr dom, @@ -12247,6 +12748,9 @@ virDomainGetFSInfo(virDomainPtr dom, * @info: pointer to a FSInfo object * * Frees all the memory occupied by @info. + * + * Since: v1.2.11 + * */ void virDomainFSInfoFree(virDomainFSInfoPtr info) @@ -12339,6 +12843,9 @@ virDomainFSInfoFree(virDomainFSInfoPtr info) * free(ifaces); * * Returns the number of interfaces on success, -1 in case of error. + * + * Since: v1.2.14 + * */ int virDomainInterfaceAddresses(virDomainPtr dom, @@ -12380,6 +12887,9 @@ virDomainInterfaceAddresses(virDomainPtr dom, * Free the interface object. The data structure is * freed and should not be used thereafter. If @iface * is NULL, then this method has no effect. + * + * Since: v1.2.14 + * */ void virDomainInterfaceFree(virDomainInterfacePtr iface) @@ -12423,6 +12933,9 @@ virDomainInterfaceFree(virDomainInterfacePtr iface) * virTypedParamsFree to free memory returned in @params. * * Returns 0 on success, -1 on error. + * + * Since: v2.0.0 + * */ int virDomainGetGuestVcpus(virDomainPtr domain, @@ -12481,6 +12994,9 @@ virDomainGetGuestVcpus(virDomainPtr domain, * low-level features a S3 sleep. * * Returns 0 on success, -1 on error. + * + * Since: v2.0.0 + * */ int virDomainSetGuestVcpus(virDomainPtr domain, @@ -12530,6 +13046,9 @@ virDomainSetGuestVcpus(virDomainPtr domain, * Note that OSes and hypervisors may require vCPU 0 to stay online. * * Returns 0 on success, -1 on error. + * + * Since: v3.1.0 + * */ int virDomainSetVcpu(virDomainPtr domain, @@ -12682,6 +13201,9 @@ virDomainSetVcpu(virDomainPtr domain, * virTypedParamsFree to free memory returned in @params. * * Returns 0 on success, -1 on error. + * + * Since: v5.7.0 + * */ int virDomainGetGuestInfo(virDomainPtr domain, unsigned int types, @@ -12756,6 +13278,9 @@ int virDomainGetGuestInfo(virDomainPtr domain, * tools to grow it without the need for polling of the data. * * Returns 0 if the operation has started, -1 on failure. + * + * Since: v3.2.0 + * */ int virDomainSetBlockThreshold(virDomainPtr domain, @@ -12805,6 +13330,9 @@ virDomainSetBlockThreshold(virDomainPtr domain, * any action for running domain. * * Returns 0 on success, -1 on failure. + * + * Since: v3.9.0 + * */ int virDomainSetLifecycleAction(virDomainPtr domain, unsigned int type, @@ -12860,6 +13388,9 @@ int virDomainSetLifecycleAction(virDomainPtr domain, * return the launch measurement. * * Returns -1 in case of failure, 0 in case of success. + * + * Since: v4.5.0 + * */ int virDomainGetLaunchSecurityInfo(virDomainPtr domain, virTypedParameterPtr *params, @@ -12926,6 +13457,9 @@ int virDomainGetLaunchSecurityInfo(virDomainPtr domain, * launch security parameters. * * Returns -1 in case of failure, 0 in case of success. + * + * Since: v8.0.0 + * */ int virDomainSetLaunchSecurityState(virDomainPtr domain, virTypedParameterPtr params, @@ -12983,6 +13517,9 @@ int virDomainSetLaunchSecurityState(virDomainPtr domain, * positive value: wait for @timeout seconds * * Returns 0 on success, -1 on failure + * + * Since: v5.10.0 + * */ int virDomainAgentSetResponseTimeout(virDomainPtr domain, @@ -13079,6 +13616,9 @@ virDomainAgentSetResponseTimeout(virDomainPtr domain, * formats if checkpoints are not involved. * * Returns 0 on success or -1 on failure. + * + * Since: v6.0.0 + * */ int virDomainBackupBegin(virDomainPtr domain, @@ -13129,6 +13669,9 @@ virDomainBackupBegin(virDomainPtr domain, * * Returns a NUL-terminated UTF-8 encoded XML instance or NULL in * case of error. The caller must free() the returned value. + * + * Since: v6.0.0 + * */ char * virDomainBackupGetXMLDesc(virDomainPtr domain, @@ -13178,6 +13721,9 @@ virDomainBackupGetXMLDesc(virDomainPtr domain, * * Returns: number of keys stored in @keys, * -1 otherwise. + * + * Since: v6.10.0 + * */ int virDomainAuthorizedSSHKeysGet(virDomainPtr domain, @@ -13246,6 +13792,9 @@ virDomainAuthorizedSSHKeysGet(virDomainPtr domain, * * Returns: 0 on success, * -1 otherwise. + * + * Since: v6.10.0 + * */ int virDomainAuthorizedSSHKeysSet(virDomainPtr domain, @@ -13314,6 +13863,9 @@ virDomainAuthorizedSSHKeysSet(virDomainPtr domain, * * Returns: number of messages stored in @msgs, * -1 otherwise. + * + * Since: v7.1.0 + * */ int virDomainGetMessages(virDomainPtr domain, @@ -13356,6 +13908,9 @@ virDomainGetMessages(virDomainPtr domain, * virConnectGetAllDomainStats. * * Returns 0 in case of success, -1 otherwise. + * + * Since: v7.2.0 + * */ int virDomainStartDirtyRateCalc(virDomainPtr domain, diff --git a/src/libvirt-host.c b/src/libvirt-host.c index 8e680cb9f9..6ba2c9e0bd 100644 --- a/src/libvirt-host.c +++ b/src/libvirt-host.c @@ -47,6 +47,9 @@ VIR_LOG_INIT("libvirt.host"); * the reference count. * * Returns 0 in case of success, -1 in case of failure + * + * Since: v0.6.0 + * */ int virConnectRef(virConnectPtr conn) @@ -85,6 +88,9 @@ virConnectRef(virConnectPtr conn) * on a connection if the application is not trustworthy. * * Returns: 0 if the identity change was accepted, -1 on error + * + * Since: v5.8.0 + * */ int virConnectSetIdentity(virConnectPtr conn, @@ -149,6 +155,9 @@ virConnectSupportsFeature(virConnectPtr conn, int feature) * hypervisor, use virConnectGetCapabilities(). * * Returns NULL in case of error, a static zero terminated string otherwise. + * + * Since: v0.0.1 + * */ const char * virConnectGetType(virConnectPtr conn) @@ -180,6 +189,9 @@ virConnectGetType(virConnectPtr conn) * Returns -1 in case of error, 0 otherwise. if the version can't be * extracted by lack of capacities returns 0 and @hvVer is 0, otherwise * @hvVer value is major * 1,000,000 + minor * 1,000 + release + * + * Since: v0.0.1 + * */ int virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer) @@ -216,6 +228,9 @@ virConnectGetVersion(virConnectPtr conn, unsigned long *hvVer) * * Returns -1 in case of failure, 0 otherwise, and values for @libVer have * the format major * 1,000,000 + minor * 1,000 + release. + * + * Since: v0.7.3 + * */ int virConnectGetLibVersion(virConnectPtr conn, unsigned long *libVer) @@ -256,6 +271,9 @@ virConnectGetLibVersion(virConnectPtr conn, unsigned long *libVer) * * Returns the hostname which must be freed by the caller, or * NULL if there was an error. + * + * Since: v0.3.0 + * */ char * virConnectGetHostname(virConnectPtr conn) @@ -295,6 +313,9 @@ virConnectGetHostname(virConnectPtr conn) * * Returns the URI string which must be freed by the caller, or * NULL if there was an error. + * + * Since: v0.3.0 + * */ char * virConnectGetURI(virConnectPtr conn) @@ -329,6 +350,9 @@ virConnectGetURI(virConnectPtr conn) * * Returns the XML string which must be freed by the caller, or * NULL if there was an error. + * + * Since: v0.8.8 + * */ char * virConnectGetSysinfo(virConnectPtr conn, unsigned int flags) @@ -367,6 +391,9 @@ virConnectGetSysinfo(virConnectPtr conn, unsigned int flags) * for "<vcpu max='...'>" in its output instead. * * Returns the maximum of virtual CPU or -1 in case of error. + * + * Since: v0.2.1 + * */ int virConnectGetMaxVcpus(virConnectPtr conn, @@ -416,6 +443,9 @@ virConnectGetMaxVcpus(virConnectPtr conn, * in a more accurate representation. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.1.0 + * */ int virNodeGetInfo(virConnectPtr conn, virNodeInfoPtr info) @@ -452,6 +482,9 @@ virNodeGetInfo(virConnectPtr conn, virNodeInfoPtr info) * Returns NULL in case of error, or an XML string * defining the capabilities. * The client must free the returned string after use. + * + * Since: v0.2.1 + * */ char * virConnectGetCapabilities(virConnectPtr conn) @@ -532,6 +565,9 @@ virConnectGetCapabilities(virConnectPtr conn) * represents all CPUs on the server. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.3 + * */ int virNodeGetCPUStats(virConnectPtr conn, @@ -619,6 +655,9 @@ virNodeGetCPUStats(virConnectPtr conn, * The cached memory usage.(KB) * * Returns -1 in case of error, 0 in case of success. + * + * Since: v0.9.3 + * */ int virNodeGetMemoryStats(virConnectPtr conn, @@ -666,6 +705,9 @@ virNodeGetMemoryStats(virConnectPtr conn, * function the returned value is in bytes. Divide by 1024 as necessary. * * Returns the available free memory in bytes or 0 in case of error + * + * Since: v0.3.3 + * */ unsigned long long virNodeGetFreeMemory(virConnectPtr conn) @@ -712,6 +754,9 @@ virNodeGetFreeMemory(virConnectPtr conn) * Returns 0 on success (i.e., the node will be suspended after a short * delay), -1 on failure (the operation is not supported, or an attempted * suspend is already underway). + * + * Since: v0.9.8 + * */ int virNodeSuspendForDuration(virConnectPtr conn, @@ -765,6 +810,9 @@ virNodeSuspendForDuration(virConnectPtr conn, * example. * * Returns 0 in case of success, and -1 in case of failure. + * + * Since: v0.10.2 + * */ int virNodeGetMemoryParameters(virConnectPtr conn, @@ -829,6 +877,9 @@ virNodeGetMemoryParameters(virConnectPtr conn, * This function may require privileged access to the hypervisor. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.10.2 + * */ int virNodeSetMemoryParameters(virConnectPtr conn, @@ -877,6 +928,9 @@ virNodeSetMemoryParameters(virConnectPtr conn, * string if the driver has not activated a security model. * * Returns 0 in case of success, -1 in case of failure + * + * Since: v0.6.1 + * */ int virNodeGetSecurityModel(virConnectPtr conn, virSecurityModelPtr secmodel) @@ -920,6 +974,9 @@ virNodeGetSecurityModel(virConnectPtr conn, virSecurityModelPtr secmodel) * whichever is smaller. * * Returns the number of entries filled in freeMems, or -1 in case of error. + * + * Since: v0.3.3 + * */ int virNodeGetCellsFreeMemory(virConnectPtr conn, unsigned long long *freeMems, @@ -958,6 +1015,9 @@ virNodeGetCellsFreeMemory(virConnectPtr conn, unsigned long long *freeMems, * Determine if the connection to the hypervisor is encrypted * * Returns 1 if encrypted, 0 if not encrypted, -1 on error + * + * Since: v0.7.3 + * */ int virConnectIsEncrypted(virConnectPtr conn) @@ -993,6 +1053,9 @@ virConnectIsEncrypted(virConnectPtr conn) * to eavesdropping (eg a UNIX domain socket, or pipe) * * Returns 1 if secure, 0 if not secure, -1 on error + * + * Since: v0.7.3 + * */ int virConnectIsSecure(virConnectPtr conn) @@ -1035,6 +1098,9 @@ virConnectIsSecure(virConnectPtr conn) * (instead of VIR_CPU_COMPARE_INCOMPATIBLE) and the error will use the * VIR_ERR_CPU_INCOMPATIBLE code with a message providing more details about * the incompatibility. + * + * Since: v0.7.5 + * */ int virConnectCompareCPU(virConnectPtr conn, @@ -1091,6 +1157,9 @@ virConnectCompareCPU(virConnectPtr conn, * VIR_CPU_COMPARE_INCOMPATIBLE) and the error will use the * VIR_ERR_CPU_INCOMPATIBLE code with a message providing more details about * the incompatibility. + * + * Since: v4.4.0 + * */ int virConnectCompareHypervisorCPU(virConnectPtr conn, @@ -1153,6 +1222,9 @@ virConnectCompareHypervisorCPU(virConnectPtr conn, * * Returns -1 on error, number of elements in @models on success (0 means * libvirt accepts any CPU model). + * + * Since: v1.1.3 + * */ int virConnectGetCPUModelNames(virConnectPtr conn, const char *arch, char ***models, @@ -1209,6 +1281,9 @@ virConnectGetCPUModelNames(virConnectPtr conn, const char *arch, char ***models, * CPU will not include features that block migration. * * Returns XML description of the computed CPU (caller frees) or NULL on error. + * + * Since: v0.7.7 + * */ char * virConnectBaselineCPU(virConnectPtr conn, @@ -1278,6 +1353,9 @@ virConnectBaselineCPU(virConnectPtr conn, * CPU will not include features that block migration. * * Returns XML description of the computed CPU (caller frees) or NULL on error. + * + * Since: v4.4.0 + * */ char * virConnectBaselineHypervisorCPU(virConnectPtr conn, @@ -1351,6 +1429,9 @@ virConnectBaselineHypervisorCPU(virConnectPtr conn, * * Returns -1 on error, 0 on success, 1 when remote party doesn't support * keepalive messages. + * + * Since: v0.9.8 + * */ int virConnectSetKeepAlive(virConnectPtr conn, @@ -1388,6 +1469,9 @@ virConnectSetKeepAlive(virConnectPtr conn, * over a channel (TCP or UNIX socket) which is not closed. * * Returns 1 if alive, 0 if dead, -1 on error + * + * Since: v0.9.8 + * */ int virConnectIsAlive(virConnectPtr conn) @@ -1434,6 +1518,9 @@ virConnectIsAlive(virConnectPtr conn) * context. * * Returns 0 on success, -1 on error + * + * Since: v0.10.0 + * */ int virConnectRegisterCloseCallback(virConnectPtr conn, @@ -1471,6 +1558,9 @@ virConnectRegisterCloseCallback(virConnectPtr conn, * registration, it will be invoked * * Returns 0 on success, -1 on error + * + * Since: v0.10.0 + * */ int virConnectUnregisterCloseCallback(virConnectPtr conn, @@ -1513,6 +1603,9 @@ virConnectUnregisterCloseCallback(virConnectPtr conn, * * Returns number of CPUs present on the host node, * or -1 if there was an error. + * + * Since: v1.0.0 + * */ int virNodeGetCPUMap(virConnectPtr conn, @@ -1599,6 +1692,9 @@ virNodeGetCPUMap(virConnectPtr conn, * Page size=1073741824 count=0 bytes=0 * * Returns: the number of entries filled in @counts or -1 in case of error. + * + * Since: v1.2.6 + * */ int virNodeGetFreePages(virConnectPtr conn, @@ -1669,6 +1765,9 @@ virNodeGetFreePages(virConnectPtr conn, * * Returns: the number of nodes successfully adjusted or -1 in * case of an error. + * + * Since: v1.2.9 + * */ int virNodeAllocPages(virConnectPtr conn, @@ -1722,6 +1821,9 @@ virNodeAllocPages(virConnectPtr conn, * responsible for freeing @params. * * Returns 0 in case of success, and -1 in case of failure. + * + * Since: v4.5.0 + * */ int virNodeGetSEVInfo(virConnectPtr conn, diff --git a/src/libvirt-interface.c b/src/libvirt-interface.c index e4e8178ba9..67dcb76efb 100644 --- a/src/libvirt-interface.c +++ b/src/libvirt-interface.c @@ -36,6 +36,9 @@ VIR_LOG_INIT("libvirt.interface"); * call. * * Returns the virConnectPtr or NULL in case of failure. + * + * Since: v0.6.4 + * */ virConnectPtr virInterfaceGetConnect(virInterfacePtr iface) @@ -76,6 +79,9 @@ virInterfaceGetConnect(virInterfacePtr iface) * extra allocated element set to NULL but not included in the return count, * to make iteration easier. The caller is responsible for calling * virStorageInterfaceFree() on each array element, then calling free() on @ifaces. + * + * Since: v0.10.2 + * */ int virConnectListAllInterfaces(virConnectPtr conn, @@ -115,6 +121,9 @@ virConnectListAllInterfaces(virConnectPtr conn, * Provides the number of active interfaces on the physical host. * * Returns the number of active interfaces found or -1 in case of error + * + * Since: v0.6.4 + * */ int virConnectNumOfInterfaces(virConnectPtr conn) @@ -158,6 +167,9 @@ virConnectNumOfInterfaces(virConnectPtr conn) * to virConnectNumOfInterfaces() and this call; you are only guaranteed that * all currently active interfaces were listed if the return is less than * @maxnames. The client must call free() on each returned name. + * + * Since: v0.6.4 + * */ int virConnectListInterfaces(virConnectPtr conn, char **const names, int maxnames) @@ -193,6 +205,9 @@ virConnectListInterfaces(virConnectPtr conn, char **const names, int maxnames) * Provides the number of defined (inactive) interfaces on the physical host. * * Returns the number of defined interface found or -1 in case of error + * + * Since: v0.7.0 + * */ int virConnectNumOfDefinedInterfaces(virConnectPtr conn) @@ -236,6 +251,9 @@ virConnectNumOfDefinedInterfaces(virConnectPtr conn) * a call to virConnectNumOfDefinedInterfaces() and this call; you are only * guaranteed that all currently defined interfaces were listed if the return * is less than @maxnames. The client must call free() on each returned name. + * + * Since: v0.7.0 + * */ int virConnectListDefinedInterfaces(virConnectPtr conn, @@ -278,6 +296,9 @@ virConnectListDefinedInterfaces(virConnectPtr conn, * * Returns a new interface object or NULL in case of failure. If the * interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised. + * + * Since: v0.6.4 + * */ virInterfacePtr virInterfaceLookupByName(virConnectPtr conn, const char *name) @@ -317,6 +338,9 @@ virInterfaceLookupByName(virConnectPtr conn, const char *name) * * Returns a new interface object or NULL in case of failure. If the * interface cannot be found, then VIR_ERR_NO_INTERFACE error is raised. + * + * Since: v0.6.4 + * */ virInterfacePtr virInterfaceLookupByMACString(virConnectPtr conn, const char *macstr) @@ -352,6 +376,9 @@ virInterfaceLookupByMACString(virConnectPtr conn, const char *macstr) * * Returns a pointer to the name or NULL, the string need not be deallocated * its lifetime will be the same as the interface object. + * + * Since: v0.6.4 + * */ const char * virInterfaceGetName(virInterfacePtr iface) @@ -376,6 +403,9 @@ virInterfaceGetName(virInterfacePtr iface) * Returns a pointer to the MAC address (in null-terminated ASCII * format) or NULL, the string need not be deallocated its lifetime * will be the same as the interface object. + * + * Since: v0.6.4 + * */ const char * virInterfaceGetMACString(virInterfacePtr iface) @@ -407,6 +437,9 @@ virInterfaceGetMACString(virInterfacePtr iface) * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case * of error. The caller must free() the returned value. + * + * Since: v0.6.4 + * */ char * virInterfaceGetXMLDesc(virInterfacePtr iface, unsigned int flags) @@ -458,6 +491,9 @@ virInterfaceGetXMLDesc(virInterfacePtr iface, unsigned int flags) * interface object is no longer needed. * * Returns NULL in case of error, a pointer to the interface otherwise + * + * Since: v0.6.4 + * */ virInterfacePtr virInterfaceDefineXML(virConnectPtr conn, const char *xml, unsigned int flags) @@ -504,6 +540,9 @@ virInterfaceDefineXML(virConnectPtr conn, const char *xml, unsigned int flags) * during the next reboot of the system running libvirtd. * * Returns 0 in case of success, -1 in case of error + * + * Since: v0.6.4 + * */ int virInterfaceUndefine(virInterfacePtr iface) @@ -547,6 +586,9 @@ virInterfaceUndefine(virInterfacePtr iface) * undefined) if virInterfaceChangeRollback() is called. * * Returns 0 in case of success, -1 in case of error + * + * Since: v0.6.4 + * */ int virInterfaceCreate(virInterfacePtr iface, unsigned int flags) @@ -594,6 +636,9 @@ virInterfaceCreate(virInterfacePtr iface, unsigned int flags) * interface definition will also bring the interface back up. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.6.4 + * */ int virInterfaceDestroy(virInterfacePtr iface, unsigned int flags) @@ -640,6 +685,9 @@ virInterfaceDestroy(virInterfacePtr iface, unsigned int flags) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.6.4 + * */ int virInterfaceRef(virInterfacePtr iface) @@ -663,6 +711,9 @@ virInterfaceRef(virInterfacePtr iface) * The data structure is freed and should not be used thereafter. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.6.4 + * */ int virInterfaceFree(virInterfacePtr iface) @@ -694,6 +745,9 @@ virInterfaceFree(virInterfacePtr iface) * VIR_ERR_INVALID_OPERATION will be logged. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.2 + * */ int virInterfaceChangeBegin(virConnectPtr conn, unsigned int flags) @@ -734,6 +788,9 @@ virInterfaceChangeBegin(virConnectPtr conn, unsigned int flags) * will be logged. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.2 + * */ int virInterfaceChangeCommit(virConnectPtr conn, unsigned int flags) @@ -774,6 +831,9 @@ virInterfaceChangeCommit(virConnectPtr conn, unsigned int flags) * will be logged. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.9.2 + * */ int virInterfaceChangeRollback(virConnectPtr conn, unsigned int flags) @@ -809,6 +869,9 @@ virInterfaceChangeRollback(virConnectPtr conn, unsigned int flags) * Determine if the interface is currently running * * Returns 1 if running, 0 if inactive, -1 on error + * + * Since: v0.7.3 + * */ int virInterfaceIsActive(virInterfacePtr iface) diff --git a/src/libvirt-network.c b/src/libvirt-network.c index 883dd40f6b..c3713dfad5 100644 --- a/src/libvirt-network.c +++ b/src/libvirt-network.c @@ -38,6 +38,9 @@ VIR_LOG_INIT("libvirt.network"); * call. * * Returns the virConnectPtr or NULL in case of failure. + * + * Since: v0.3.0 + * */ virConnectPtr virNetworkGetConnect(virNetworkPtr net) @@ -86,6 +89,9 @@ virNetworkGetConnect(virNetworkPtr net) * extra allocated element set to NULL but not included in the return count, * to make iteration easier. The caller is responsible for calling * virNetworkFree() on each array element, then calling free() on @nets. + * + * Since: v0.10.2 + * */ int virConnectListAllNetworks(virConnectPtr conn, @@ -125,6 +131,9 @@ virConnectListAllNetworks(virConnectPtr conn, * Provides the number of active networks. * * Returns the number of network found or -1 in case of error + * + * Since: v0.2.0 + * */ int virConnectNumOfNetworks(virConnectPtr conn) @@ -167,6 +176,9 @@ virConnectNumOfNetworks(virConnectPtr conn) * to virConnectNumOfNetworks() and this call; you are only guaranteed that * all currently active networks were listed if the return is less than * @maxnames. The client must call free() on each returned name. + * + * Since: v0.2.0 + * */ int virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames) @@ -202,6 +214,9 @@ virConnectListNetworks(virConnectPtr conn, char **const names, int maxnames) * Provides the number of inactive networks. * * Returns the number of networks found or -1 in case of error + * + * Since: v0.2.0 + * */ int virConnectNumOfDefinedNetworks(virConnectPtr conn) @@ -244,6 +259,9 @@ virConnectNumOfDefinedNetworks(virConnectPtr conn) * a call to virConnectNumOfDefinedNetworks() and this call; you are only * guaranteed that all currently defined networks were listed if the return * is less than @maxnames. The client must call free() on each returned name. + * + * Since: v0.2.0 + * */ int virConnectListDefinedNetworks(virConnectPtr conn, char **const names, @@ -285,6 +303,9 @@ virConnectListDefinedNetworks(virConnectPtr conn, char **const names, * * Returns a new network object or NULL in case of failure. If the * network cannot be found, then VIR_ERR_NO_NETWORK error is raised. + * + * Since: v0.2.0 + * */ virNetworkPtr virNetworkLookupByName(virConnectPtr conn, const char *name) @@ -324,6 +345,9 @@ virNetworkLookupByName(virConnectPtr conn, const char *name) * * Returns a new network object or NULL in case of failure. If the * network cannot be found, then VIR_ERR_NO_NETWORK error is raised. + * + * Since: v0.2.0 + * */ virNetworkPtr virNetworkLookupByUUID(virConnectPtr conn, const unsigned char *uuid) @@ -360,6 +384,9 @@ virNetworkLookupByUUID(virConnectPtr conn, const unsigned char *uuid) * * Returns a new network object or NULL in case of failure. If the * network cannot be found, then VIR_ERR_NO_NETWORK error is raised. + * + * Since: v0.2.0 + * */ virNetworkPtr virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr) @@ -399,6 +426,9 @@ virNetworkLookupByUUIDString(virConnectPtr conn, const char *uuidstr) * network object is no longer needed. * * Returns a new network object or NULL in case of failure + * + * Since: v0.2.0 + * */ virNetworkPtr virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc) @@ -440,6 +470,9 @@ virNetworkCreateXML(virConnectPtr conn, const char *xmlDesc) * network object is no longer needed. * * Returns a new network object or NULL in case of failure + * + * Since: v7.8.0 + * */ virNetworkPtr virNetworkCreateXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int flags) @@ -480,6 +513,9 @@ virNetworkCreateXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int f * network object is no longer needed. * * Returns NULL in case of error, a pointer to the network otherwise + * + * Since: v0.2.0 + * */ virNetworkPtr virNetworkDefineXML(virConnectPtr conn, const char *xml) @@ -521,6 +557,9 @@ virNetworkDefineXML(virConnectPtr conn, const char *xml) * network object is no longer needed. * * Returns NULL in case of error, a pointer to the network otherwise + * + * Since: v7.7.0 + * */ virNetworkPtr virNetworkDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags) @@ -556,6 +595,9 @@ virNetworkDefineXMLFlags(virConnectPtr conn, const char *xml, unsigned int flags * Undefine a network but does not stop it if it is running * * Returns 0 in case of success, -1 in case of error + * + * Since: v0.2.0 + * */ int virNetworkUndefine(virNetworkPtr network) @@ -604,6 +646,9 @@ virNetworkUndefine(virNetworkPtr network) * running state, its persistent configuration, or both. * * Returns 0 in case of success, -1 in case of error + * + * Since: v1.0.0 + * */ int virNetworkUpdate(virNetworkPtr network, @@ -670,6 +715,9 @@ virNetworkUpdate(virNetworkPtr network, * moves from the defined to the running networks pools. * * Returns 0 in case of success, -1 in case of error + * + * Since: v0.2.0 + * */ int virNetworkCreate(virNetworkPtr network) @@ -710,6 +758,9 @@ virNetworkCreate(virNetworkPtr network) * This function may require privileged access * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.2.0 + * */ int virNetworkDestroy(virNetworkPtr network) @@ -748,6 +799,9 @@ virNetworkDestroy(virNetworkPtr network) * The data structure is freed and should not be used thereafter. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.2.0 + * */ int virNetworkFree(virNetworkPtr network) @@ -779,6 +833,9 @@ virNetworkFree(virNetworkPtr network) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.6.0 + * */ int virNetworkRef(virNetworkPtr network) @@ -802,6 +859,9 @@ virNetworkRef(virNetworkPtr network) * * Returns a pointer to the name or NULL, the string need not be deallocated * its lifetime will be the same as the network object. + * + * Since: v0.2.0 + * */ const char * virNetworkGetName(virNetworkPtr network) @@ -824,6 +884,9 @@ virNetworkGetName(virNetworkPtr network) * Get the UUID for a network * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.2.0 + * */ int virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid) @@ -854,6 +917,9 @@ virNetworkGetUUID(virNetworkPtr network, unsigned char *uuid) * UUID see RFC4122. * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.2.0 + * */ int virNetworkGetUUIDString(virNetworkPtr network, char *buf) @@ -889,6 +955,9 @@ virNetworkGetUUIDString(virNetworkPtr network, char *buf) * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case * of error. The caller must free() the returned value. + * + * Since: v0.2.0 + * */ char * virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags) @@ -926,6 +995,9 @@ virNetworkGetXMLDesc(virNetworkPtr network, unsigned int flags) * * Returns a 0 terminated interface name, or NULL in case of * error. The caller must free() the returned value. + * + * Since: v0.2.0 + * */ char * virNetworkGetBridgeName(virNetworkPtr network) @@ -964,6 +1036,9 @@ virNetworkGetBridgeName(virNetworkPtr network) * machine boots. * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.2.1 + * */ int virNetworkGetAutostart(virNetworkPtr network, @@ -1004,6 +1079,9 @@ virNetworkGetAutostart(virNetworkPtr network, * when the host machine boots. * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.2.1 + * */ int virNetworkSetAutostart(virNetworkPtr network, @@ -1042,6 +1120,9 @@ virNetworkSetAutostart(virNetworkPtr network, * Determine if the network is currently running * * Returns 1 if running, 0 if inactive, -1 on error + * + * Since: v0.7.3 + * */ int virNetworkIsActive(virNetworkPtr net) @@ -1075,6 +1156,9 @@ virNetworkIsActive(virNetworkPtr net) * which means it will still exist after shutting down * * Returns 1 if persistent, 0 if transient, -1 on error + * + * Since: v0.7.3 + * */ int virNetworkIsPersistent(virNetworkPtr net) @@ -1134,6 +1218,9 @@ virNetworkIsPersistent(virNetworkPtr net) * be passed to the virConnectNetworkEventDeregisterAny() method. * * Returns a callback identifier on success, -1 on failure. + * + * Since: v1.2.1 + * */ int virConnectNetworkEventRegisterAny(virConnectPtr conn, @@ -1195,6 +1282,9 @@ virConnectNetworkEventRegisterAny(virConnectPtr conn, * value obtained from a previous virConnectNetworkEventRegisterAny() method. * * Returns 0 on success, -1 on failure + * + * Since: v1.2.1 + * */ int virConnectNetworkEventDeregisterAny(virConnectPtr conn, @@ -1297,6 +1387,9 @@ virConnectNetworkEventDeregisterAny(virConnectPtr conn, * Returns the number of leases found or -1 and sets @leases to NULL in * case of error. * + * Since: v1.2.6 + * + * */ int virNetworkGetDHCPLeases(virNetworkPtr network, @@ -1338,6 +1431,9 @@ virNetworkGetDHCPLeases(virNetworkPtr network, * @lease: pointer to a leases object * * Frees all the memory occupied by @lease. + * + * Since: v1.2.6 + * */ void virNetworkDHCPLeaseFree(virNetworkDHCPLeasePtr lease) @@ -1366,6 +1462,9 @@ virNetworkDHCPLeaseFree(virNetworkDHCPLeasePtr lease) * * Returns a new network port object or NULL in case of failure. If the * network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised. + * + * Since: v5.5.0 + * */ virNetworkPortPtr virNetworkPortLookupByUUID(virNetworkPtr net, @@ -1403,6 +1502,9 @@ virNetworkPortLookupByUUID(virNetworkPtr net, * * Returns a new network port object or NULL in case of failure. If the * network port cannot be found, then VIR_ERR_NO_NETWORK_PORT error is raised. + * + * Since: v5.5.0 + * */ virNetworkPortPtr virNetworkPortLookupByUUIDString(virNetworkPtr net, @@ -1443,6 +1545,9 @@ virNetworkPortLookupByUUIDString(virNetworkPtr net, * includes bandwidth parameters. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v5.5.0 + * */ int virNetworkPortSetParameters(virNetworkPortPtr port, @@ -1491,6 +1596,9 @@ virNetworkPortSetParameters(virNetworkPortPtr port, * on success. * * Returns -1 in case of error, 0 in case of success. + * + * Since: v5.5.0 + * */ int virNetworkPortGetParameters(virNetworkPortPtr port, @@ -1535,6 +1643,9 @@ virNetworkPortGetParameters(virNetworkPortPtr port, * network port object is no longer needed. * * Returns a new network port object or NULL in case of failure + * + * Since: v5.5.0 + * */ virNetworkPortPtr virNetworkPortCreateXML(virNetworkPtr net, @@ -1573,6 +1684,9 @@ virNetworkPortCreateXML(virNetworkPtr net, * call. * * Returns the virNetworkPtr or NULL in case of failure. + * + * Since: v5.5.0 + * */ virNetworkPtr virNetworkPortGetNetwork(virNetworkPortPtr port) @@ -1597,6 +1711,9 @@ virNetworkPortGetNetwork(virNetworkPortPtr port) * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case of error. * the caller must free() the returned value. + * + * Since: v5.5.0 + * */ char * virNetworkPortGetXMLDesc(virNetworkPortPtr port, @@ -1634,6 +1751,9 @@ virNetworkPortGetXMLDesc(virNetworkPortPtr port, * Get the UUID for a network port * * Returns -1 in case of error, 0 in case of success + * + * Since: v5.5.0 + * */ int virNetworkPortGetUUID(virNetworkPortPtr port, @@ -1665,6 +1785,9 @@ virNetworkPortGetUUID(virNetworkPortPtr port, * UUID see RFC4122. * * Returns -1 in case of error, 0 in case of success + * + * Since: v5.5.0 + * */ int virNetworkPortGetUUIDString(virNetworkPortPtr port, @@ -1697,6 +1820,9 @@ virNetworkPortGetUUIDString(virNetworkPortPtr port, * port. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v5.5.0 + * */ int virNetworkPortDelete(virNetworkPortPtr port, @@ -1745,6 +1871,9 @@ virNetworkPortDelete(virNetworkPortPtr port, * in the return count, to make iteration easier. The caller is responsible * for calling virNetworkPortFree() on each array element, then calling * free() on @ports. + * + * Since: v5.5.0 + * */ int virNetworkListAllPorts(virNetworkPtr network, @@ -1782,6 +1911,9 @@ virNetworkListAllPorts(virNetworkPtr network, * The data structure is freed and should not be used thereafter. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v5.5.0 + * */ int virNetworkPortFree(virNetworkPortPtr port) @@ -1813,6 +1945,9 @@ virNetworkPortFree(virNetworkPortPtr port) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v5.5.0 + * */ int virNetworkPortRef(virNetworkPortPtr port) diff --git a/src/libvirt-nodedev.c b/src/libvirt-nodedev.c index 3695b39270..3f23267b7a 100644 --- a/src/libvirt-nodedev.c +++ b/src/libvirt-nodedev.c @@ -40,6 +40,9 @@ VIR_LOG_INIT("libvirt.nodedev"); * will be restricted to devices with the specified capability * * Returns the number of node devices or -1 in case of error + * + * Since: v0.5.0 + * */ int virNodeNumOfDevices(virConnectPtr conn, const char *cap, unsigned int flags) @@ -86,6 +89,9 @@ virNodeNumOfDevices(virConnectPtr conn, const char *cap, unsigned int flags) * count, to make iteration easier. The caller is responsible for calling * virNodeDeviceFree() on each array element, then calling free() on * @devices. + * + * Since: v0.10.2 + * */ int virConnectListAllNodeDevices(virConnectPtr conn, @@ -135,6 +141,9 @@ virConnectListAllNodeDevices(virConnectPtr conn, * will be restricted to devices with the specified capability * * Returns the number of node devices found or -1 in case of error + * + * Since: v0.5.0 + * */ int virNodeListDevices(virConnectPtr conn, @@ -178,6 +187,9 @@ virNodeListDevices(virConnectPtr conn, * node device object is no longer needed. * * Returns a virNodeDevicePtr if found, NULL otherwise. + * + * Since: v0.5.0 + * */ virNodeDevicePtr virNodeDeviceLookupByName(virConnectPtr conn, const char *name) @@ -218,6 +230,9 @@ virNodeDeviceLookupByName(virConnectPtr conn, const char *name) * node device object is no longer needed. * * Returns a virNodeDevicePtr if found, NULL otherwise. + * + * Since: v1.0.3 + * */ virNodeDevicePtr virNodeDeviceLookupSCSIHostByWWN(virConnectPtr conn, @@ -260,6 +275,9 @@ virNodeDeviceLookupSCSIHostByWWN(virConnectPtr conn, * the device. * * Returns the XML document, or NULL on error + * + * Since: v0.5.0 + * */ char * virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags) @@ -293,6 +311,9 @@ virNodeDeviceGetXMLDesc(virNodeDevicePtr dev, unsigned int flags) * Just return the device name * * Returns the device name or NULL in case of error + * + * Since: v0.5.0 + * */ const char * virNodeDeviceGetName(virNodeDevicePtr dev) @@ -315,6 +336,9 @@ virNodeDeviceGetName(virNodeDevicePtr dev) * * Returns the name of the device's parent, or NULL if an * error occurred or when the device has no parent. + * + * Since: v0.5.0 + * */ const char * virNodeDeviceGetParent(virNodeDevicePtr dev) @@ -346,6 +370,9 @@ virNodeDeviceGetParent(virNodeDevicePtr dev) * * Returns the number of capabilities supported by the device or -1 * in case of error. + * + * Since: v0.5.0 + * */ int virNodeDeviceNumOfCaps(virNodeDevicePtr dev) @@ -382,6 +409,9 @@ virNodeDeviceNumOfCaps(virNodeDevicePtr dev) * * Returns the number of capability names listed in @names or -1 * in case of error. + * + * Since: v0.5.0 + * */ int virNodeDeviceListCaps(virNodeDevicePtr dev, @@ -421,6 +451,9 @@ virNodeDeviceListCaps(virNodeDevicePtr dev, * this was the last reference. * * Returns the 0 for success, -1 for error. + * + * Since: v0.5.0 + * */ int virNodeDeviceFree(virNodeDevicePtr dev) @@ -452,6 +485,9 @@ virNodeDeviceFree(virNodeDevicePtr dev) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.6.0 + * */ int virNodeDeviceRef(virNodeDevicePtr dev) @@ -490,6 +526,9 @@ virNodeDeviceRef(virNodeDevicePtr dev) * API should be used instead. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.6.1 + * */ int virNodeDeviceDettach(virNodeDevicePtr dev) @@ -543,6 +582,9 @@ virNodeDeviceDettach(virNodeDevicePtr dev) * to the node using the virNodeDeviceReAttach() method. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v1.0.5 + * */ int virNodeDeviceDetachFlags(virNodeDevicePtr dev, @@ -588,6 +630,9 @@ virNodeDeviceDetachFlags(virNodeDevicePtr dev, * If the device is currently in use by a guest, this method may fail. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.6.1 + * */ int virNodeDeviceReAttach(virNodeDevicePtr dev) @@ -631,6 +676,9 @@ virNodeDeviceReAttach(virNodeDevicePtr dev) * this function may fail. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.6.1 + * */ int virNodeDeviceReset(virNodeDevicePtr dev) @@ -671,6 +719,9 @@ virNodeDeviceReset(virNodeDevicePtr dev) * node device object is no longer needed. * * Returns a node device object if successful, NULL in case of failure + * + * Since: v0.6.3 + * */ virNodeDevicePtr virNodeDeviceCreateXML(virConnectPtr conn, @@ -710,6 +761,9 @@ virNodeDeviceCreateXML(virConnectPtr conn, * may require privileged access. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.6.3 + * */ int virNodeDeviceDestroy(virNodeDevicePtr dev) @@ -750,6 +804,9 @@ virNodeDeviceDestroy(virNodeDevicePtr dev) * node device object is no longer needed. * * Returns a node device object if successful, NULL in case of failure + * + * Since: v7.3.0 + * */ virNodeDevicePtr virNodeDeviceDefineXML(virConnectPtr conn, @@ -789,6 +846,9 @@ virNodeDeviceDefineXML(virConnectPtr conn, * operating system. This function may require privileged access. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v7.3.0 + * */ int virNodeDeviceUndefine(virNodeDevicePtr dev, @@ -826,6 +886,9 @@ virNodeDeviceUndefine(virNodeDevicePtr dev, * Start a defined node device: * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.5.0 + * */ int virNodeDeviceCreate(virNodeDevicePtr dev, @@ -889,6 +952,9 @@ virNodeDeviceCreate(virNodeDevicePtr dev, * be passed to the virConnectNodeDeviceEventDeregisterAny() method. * * Returns a callback identifier on success, -1 on failure. + * + * Since: v2.2.0 + * */ int virConnectNodeDeviceEventRegisterAny(virConnectPtr conn, @@ -953,6 +1019,9 @@ virConnectNodeDeviceEventRegisterAny(virConnectPtr conn, * value obtained from a previous virConnectNodeDeviceEventRegisterAny() method. * * Returns 0 on success, -1 on failure. + * + * Since: v2.2.0 + * */ int virConnectNodeDeviceEventDeregisterAny(virConnectPtr conn, @@ -990,6 +1059,9 @@ virConnectNodeDeviceEventDeregisterAny(virConnectPtr conn, * boots or the parent device becomes available. * * Returns -1 in case of error, 0 in case of success + * + * Since: v7.8.0 + * */ int virNodeDeviceSetAutostart(virNodeDevicePtr dev, @@ -1029,6 +1101,9 @@ virNodeDeviceSetAutostart(virNodeDevicePtr dev, * becomes available. * * Returns -1 in case of error, 0 in case of success + * + * Since: v7.8.0 + * */ int virNodeDeviceGetAutostart(virNodeDevicePtr dev, @@ -1065,6 +1140,9 @@ virNodeDeviceGetAutostart(virNodeDevicePtr dev, * which means it will still exist after shutting down * * Returns 1 if persistent, 0 if transient, -1 on error + * + * Since: v7.8.0 + * */ int virNodeDeviceIsPersistent(virNodeDevicePtr dev) @@ -1098,6 +1176,9 @@ virNodeDeviceIsPersistent(virNodeDevicePtr dev) * Determine if the node device is currently active * * Returns 1 if active, 0 if inactive, -1 on error + * + * Since: v7.8.0 + * */ int virNodeDeviceIsActive(virNodeDevicePtr dev) { diff --git a/src/libvirt-nwfilter.c b/src/libvirt-nwfilter.c index 73b061152e..e3d4375bad 100644 --- a/src/libvirt-nwfilter.c +++ b/src/libvirt-nwfilter.c @@ -35,6 +35,9 @@ VIR_LOG_INIT("libvirt.nwfilter"); * Provides the number of nwfilters. * * Returns the number of nwfilters found or -1 in case of error + * + * Since: v0.8.0 + * */ int virConnectNumOfNWFilters(virConnectPtr conn) @@ -77,6 +80,9 @@ virConnectNumOfNWFilters(virConnectPtr conn) * have an extra allocated element set to NULL but not included in the return count, * to make iteration easier. The caller is responsible for calling * virNWFilterFree() on each array element, then calling free() on @filters. + * + * Since: v0.10.2 + * */ int virConnectListAllNWFilters(virConnectPtr conn, @@ -121,6 +127,9 @@ virConnectListAllNWFilters(virConnectPtr conn, * virConnectListAllNWFilters(). * * Returns the number of network filters found or -1 in case of error + * + * Since: v0.8.0 + * */ int virConnectListNWFilters(virConnectPtr conn, char **const names, int maxnames) @@ -161,6 +170,9 @@ virConnectListNWFilters(virConnectPtr conn, char **const names, int maxnames) * * Returns a new nwfilter object or NULL in case of failure. If the * network filter cannot be found, then VIR_ERR_NO_NWFILTER error is raised. + * + * Since: v0.8.0 + * */ virNWFilterPtr virNWFilterLookupByName(virConnectPtr conn, const char *name) @@ -200,6 +212,9 @@ virNWFilterLookupByName(virConnectPtr conn, const char *name) * * Returns a new nwfilter object or NULL in case of failure. If the * nwfdilter cannot be found, then VIR_ERR_NO_NWFILTER error is raised. + * + * Since: v0.8.0 + * */ virNWFilterPtr virNWFilterLookupByUUID(virConnectPtr conn, const unsigned char *uuid) @@ -239,6 +254,9 @@ virNWFilterLookupByUUID(virConnectPtr conn, const unsigned char *uuid) * * Returns a new nwfilter object or NULL in case of failure. If the * nwfilter cannot be found, then VIR_ERR_NO_NWFILTER error is raised. + * + * Since: v0.8.0 + * */ virNWFilterPtr virNWFilterLookupByUUIDString(virConnectPtr conn, const char *uuidstr) @@ -274,6 +292,9 @@ virNWFilterLookupByUUIDString(virConnectPtr conn, const char *uuidstr) * The data structure is freed and should not be used thereafter. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.8.0 + * */ int virNWFilterFree(virNWFilterPtr nwfilter) @@ -297,6 +318,9 @@ virNWFilterFree(virNWFilterPtr nwfilter) * * Returns a pointer to the name or NULL, the string need not be deallocated * its lifetime will be the same as the nwfilter object. + * + * Since: v0.8.0 + * */ const char * virNWFilterGetName(virNWFilterPtr nwfilter) @@ -319,6 +343,9 @@ virNWFilterGetName(virNWFilterPtr nwfilter) * Get the UUID for a network filter * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.8.0 + * */ int virNWFilterGetUUID(virNWFilterPtr nwfilter, unsigned char *uuid) @@ -349,6 +376,9 @@ virNWFilterGetUUID(virNWFilterPtr nwfilter, unsigned char *uuid) * UUID see RFC4122. * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.8.0 + * */ int virNWFilterGetUUIDString(virNWFilterPtr nwfilter, char *buf) @@ -381,6 +411,9 @@ virNWFilterGetUUIDString(virNWFilterPtr nwfilter, char *buf) * nwfilter object is no longer needed. * * Returns a new nwfilter object or NULL in case of failure + * + * Since: v0.8.0 + * */ virNWFilterPtr virNWFilterDefineXML(virConnectPtr conn, const char *xmlDesc) @@ -422,6 +455,9 @@ virNWFilterDefineXML(virConnectPtr conn, const char *xmlDesc) * nwfilter object is no longer needed. * * Returns a new nwfilter object or NULL in case of failure + * + * Since: v7.7.0 + * */ virNWFilterPtr virNWFilterDefineXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int flags) @@ -459,6 +495,9 @@ virNWFilterDefineXMLFlags(virConnectPtr conn, const char *xmlDesc, unsigned int * associated virNWFilterPtr object. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v0.8.0 + * */ int virNWFilterUndefine(virNWFilterPtr nwfilter) @@ -499,6 +538,9 @@ virNWFilterUndefine(virNWFilterPtr nwfilter) * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case * of error. The caller must free() the returned value. + * + * Since: v0.8.0 + * */ char * virNWFilterGetXMLDesc(virNWFilterPtr nwfilter, unsigned int flags) @@ -543,6 +585,9 @@ virNWFilterGetXMLDesc(virNWFilterPtr nwfilter, unsigned int flags) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.8.0 + * */ int virNWFilterRef(virNWFilterPtr nwfilter) @@ -574,6 +619,9 @@ virNWFilterRef(virNWFilterPtr nwfilter) * have an extra allocated element set to NULL but not included in the return count, * to make iteration easier. The caller is responsible for calling * virNWFilterFree() on each array element, then calling free() on @filters. + * + * Since: v4.5.0 + * */ int virConnectListAllNWFilterBindings(virConnectPtr conn, @@ -620,6 +668,9 @@ virConnectListAllNWFilterBindings(virConnectPtr conn, * Returns a new binding object or NULL in case of failure. If the * network filter cannot be found, then VIR_ERR_NO_NWFILTER_BINDING * error is raised. + * + * Since: v4.5.0 + * */ virNWFilterBindingPtr virNWFilterBindingLookupByPortDev(virConnectPtr conn, const char *portdev) @@ -655,6 +706,9 @@ virNWFilterBindingLookupByPortDev(virConnectPtr conn, const char *portdev) * The data structure is freed and should not be used thereafter. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v4.5.0 + * */ int virNWFilterBindingFree(virNWFilterBindingPtr binding) @@ -678,6 +732,9 @@ virNWFilterBindingFree(virNWFilterBindingPtr binding) * * Returns a pointer to the name or NULL, the string need not be deallocated * its lifetime will be the same as the binding object. + * + * Since: v4.5.0 + * */ const char * virNWFilterBindingGetPortDev(virNWFilterBindingPtr binding) @@ -700,6 +757,9 @@ virNWFilterBindingGetPortDev(virNWFilterBindingPtr binding) * * Returns a pointer to the name or NULL, the string need not be deallocated * its lifetime will be the same as the binding object. + * + * Since: v4.5.0 + * */ const char * virNWFilterBindingGetFilterName(virNWFilterBindingPtr binding) @@ -734,6 +794,9 @@ virNWFilterBindingGetFilterName(virNWFilterBindingPtr binding) * binding object is no longer needed. * * Returns a new binding object or NULL in case of failure + * + * Since: v4.5.0 + * */ virNWFilterBindingPtr virNWFilterBindingCreateXML(virConnectPtr conn, const char *xml, unsigned int flags) @@ -775,6 +838,9 @@ virNWFilterBindingCreateXML(virConnectPtr conn, const char *xml, unsigned int fl * would be accomplished by using virNWFilterBindingCreateXML. * * Returns 0 in case of success and -1 in case of failure. + * + * Since: v4.5.0 + * */ int virNWFilterBindingDelete(virNWFilterBindingPtr binding) @@ -815,6 +881,9 @@ virNWFilterBindingDelete(virNWFilterBindingPtr binding) * * Returns a 0 terminated UTF-8 encoded XML instance, or NULL in case * of error. The caller must free() the returned value. + * + * Since: v4.5.0 + * */ char * virNWFilterBindingGetXMLDesc(virNWFilterBindingPtr binding, unsigned int flags) @@ -859,6 +928,9 @@ virNWFilterBindingGetXMLDesc(virNWFilterBindingPtr binding, unsigned int flags) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v4.5.0 + * */ int virNWFilterBindingRef(virNWFilterBindingPtr binding) diff --git a/src/libvirt-secret.c b/src/libvirt-secret.c index d2a3a4bd9d..e0d14f6e4d 100644 --- a/src/libvirt-secret.c +++ b/src/libvirt-secret.c @@ -35,6 +35,9 @@ VIR_LOG_INIT("libvirt.secret"); * counter on the connection is not increased by this call. * * Returns the virConnectPtr or NULL in case of failure. + * + * Since: v0.7.1 + * */ virConnectPtr virSecretGetConnect(virSecretPtr secret) @@ -56,6 +59,9 @@ virSecretGetConnect(virSecretPtr secret) * Fetch number of currently defined secrets. * * Returns the number currently defined secrets. + * + * Since: v0.7.1 + * */ int virConnectNumOfSecrets(virConnectPtr conn) @@ -116,6 +122,9 @@ virConnectNumOfSecrets(virConnectPtr conn) * have an extra allocated element set to NULL but not included in the return count, * to make iteration easier. The caller is responsible for calling * virSecretFree() on each array element, then calling free() on @secrets. + * + * Since: v0.10.2 + * */ int virConnectListAllSecrets(virConnectPtr conn, @@ -160,6 +169,9 @@ virConnectListAllSecrets(virConnectPtr conn, * virConnectListAllSecrets(). * * Returns the number of UUIDs provided in the array, or -1 on failure. + * + * Since: v0.7.1 + * */ int virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids) @@ -202,6 +214,9 @@ virConnectListSecrets(virConnectPtr conn, char **uuids, int maxuuids) * * Returns a new secret object or NULL in case of failure. If the * secret cannot be found, then VIR_ERR_NO_SECRET error is raised. + * + * Since: v0.7.1 + * */ virSecretPtr virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid) @@ -243,6 +258,9 @@ virSecretLookupByUUID(virConnectPtr conn, const unsigned char *uuid) * * Returns a new secret object or NULL in case of failure. If the * secret cannot be found, then VIR_ERR_NO_SECRET error is raised. + * + * Since: v0.7.1 + * */ virSecretPtr virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr) @@ -285,6 +303,9 @@ virSecretLookupByUUIDString(virConnectPtr conn, const char *uuidstr) * * Returns a new secret object or NULL in case of failure. If the * secret cannot be found, then VIR_ERR_NO_SECRET error is raised. + * + * Since: v0.7.1 + * */ virSecretPtr virSecretLookupByUsage(virConnectPtr conn, @@ -332,6 +353,9 @@ virSecretLookupByUsage(virConnectPtr conn, * secret object is no longer needed. * * Returns a secret on success, NULL on failure. + * + * Since: v0.7.1 + * */ virSecretPtr virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags) @@ -370,6 +394,9 @@ virSecretDefineXML(virConnectPtr conn, const char *xml, unsigned int flags) * * Returns 0 on success with the uuid buffer being filled, or * -1 upon failure. + * + * Since: v0.7.1 + * */ int virSecretGetUUID(virSecretPtr secret, unsigned char *uuid) @@ -400,6 +427,9 @@ virSecretGetUUID(virSecretPtr secret, unsigned char *uuid) * UUID see RFC4122. * * Returns -1 in case of error, 0 in case of success + * + * Since: v0.7.1 + * */ int virSecretGetUUIDString(virSecretPtr secret, char *buf) @@ -432,6 +462,9 @@ virSecretGetUUIDString(virSecretPtr secret, char *buf) * * Returns a positive integer identifying the type of object, * or -1 upon error. + * + * Since: v0.7.1 + * */ int virSecretGetUsageType(virSecretPtr secret) @@ -461,6 +494,9 @@ virSecretGetUsageType(virSecretPtr secret) * * Returns a string identifying the object using the secret, * or NULL upon error + * + * Since: v0.7.1 + * */ const char * virSecretGetUsageID(virSecretPtr secret) @@ -484,6 +520,9 @@ virSecretGetUsageID(virSecretPtr secret) * * Returns the XML document on success, NULL on failure. The caller must * free() the XML. + * + * Since: v0.7.1 + * */ char * virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags) @@ -524,6 +563,9 @@ virSecretGetXMLDesc(virSecretPtr secret, unsigned int flags) * Sets the value of a secret. * * Returns 0 on success, -1 on failure. + * + * Since: v0.7.1 + * */ int virSecretSetValue(virSecretPtr secret, const unsigned char *value, @@ -569,6 +611,9 @@ virSecretSetValue(virSecretPtr secret, const unsigned char *value, * * Returns the secret value on success, NULL on failure. The caller must * free() the secret value. + * + * Since: v0.7.1 + * */ unsigned char * virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags) @@ -610,6 +655,9 @@ virSecretGetValue(virSecretPtr secret, size_t *value_size, unsigned int flags) * virSecretPtr object. * * Returns 0 on success, -1 on failure. + * + * Since: v0.7.1 + * */ int virSecretUndefine(virSecretPtr secret) @@ -657,6 +705,9 @@ virSecretUndefine(virSecretPtr secret) * increment the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.7.1 + * */ int virSecretRef(virSecretPtr secret) @@ -679,6 +730,9 @@ virSecretRef(virSecretPtr secret) * Release the secret handle. The underlying secret continues to exist. * * Returns 0 on success, or -1 on error + * + * Since: v0.7.1 + * */ int virSecretFree(virSecretPtr secret) @@ -728,6 +782,9 @@ virSecretFree(virSecretPtr secret) * be passed to the virConnectSecretEventDeregisterAny() method. * * Returns a callback identifier on success, -1 on failure. + * + * Since: v3.0.0 + * */ int virConnectSecretEventRegisterAny(virConnectPtr conn, @@ -794,6 +851,9 @@ virConnectSecretEventRegisterAny(virConnectPtr conn, * value obtained from a previous virConnectSecretEventRegisterAny() method. * * Returns 0 on success, -1 on failure. + * + * Since: v3.0.0 + * */ int virConnectSecretEventDeregisterAny(virConnectPtr conn, diff --git a/src/libvirt-storage.c b/src/libvirt-storage.c index cbc522b300..61d062f847 100644 --- a/src/libvirt-storage.c +++ b/src/libvirt-storage.c @@ -37,6 +37,9 @@ VIR_LOG_INIT("libvirt.storage"); * call. * * Returns the virConnectPtr or NULL in case of failure. + * + * Since: v0.4.1 + * */ virConnectPtr virStoragePoolGetConnect(virStoragePoolPtr pool) @@ -104,6 +107,9 @@ virStoragePoolGetConnect(virStoragePoolPtr pool) * in the return count, to make iteration easier. The caller is responsible * for calling virStoragePoolFree() on each array element, then calling * free() on @pools. + * + * Since: v0.10.2 + * */ int virConnectListAllStoragePools(virConnectPtr conn, @@ -143,6 +149,9 @@ virConnectListAllStoragePools(virConnectPtr conn, * Provides the number of active storage pools * * Returns the number of pools found, or -1 on error + * + * Since: v0.4.1 + * */ int virConnectNumOfStoragePools(virConnectPtr conn) @@ -187,6 +196,9 @@ virConnectNumOfStoragePools(virConnectPtr conn) * virConnectNumOfStoragePools() and this call; you are only guaranteed * that all currently active pools were listed if the return is less than * @maxnames. The client must call free() on each returned name. + * + * Since: v0.4.1 + * */ int virConnectListStoragePools(virConnectPtr conn, @@ -224,6 +236,9 @@ virConnectListStoragePools(virConnectPtr conn, * Provides the number of inactive storage pools * * Returns the number of pools found, or -1 on error + * + * Since: v0.4.1 + * */ int virConnectNumOfDefinedStoragePools(virConnectPtr conn) @@ -268,6 +283,9 @@ virConnectNumOfDefinedStoragePools(virConnectPtr conn) * a call to virConnectNumOfDefinedStoragePools() and this call; you are only * guaranteed that all currently defined pools were listed if the return * is less than @maxnames. The client must call free() on each returned name. + * + * Since: v0.4.1 + * */ int virConnectListDefinedStoragePools(virConnectPtr conn, @@ -318,6 +336,9 @@ virConnectListDefinedStoragePools(virConnectPtr conn, * Returns an xml document consisting of a SourceList element * containing a source document appropriate to the given pool * type for each discovered source. + * + * Since: v0.4.6 + * */ char * virConnectFindStoragePoolSources(virConnectPtr conn, @@ -361,6 +382,9 @@ virConnectFindStoragePoolSources(virConnectPtr conn, * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if no matching pool is found + * + * Since: v0.4.1 + * */ virStoragePoolPtr virStoragePoolLookupByName(virConnectPtr conn, @@ -400,6 +424,9 @@ virStoragePoolLookupByName(virConnectPtr conn, * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if no matching pool is found + * + * Since: v0.4.1 + * */ virStoragePoolPtr virStoragePoolLookupByUUID(virConnectPtr conn, @@ -439,6 +466,9 @@ virStoragePoolLookupByUUID(virConnectPtr conn, * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if no matching pool is found + * + * Since: v0.4.1 + * */ virStoragePoolPtr virStoragePoolLookupByUUIDString(virConnectPtr conn, @@ -477,6 +507,9 @@ virStoragePoolLookupByUUIDString(virConnectPtr conn, * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if no matching pool is found + * + * Since: v0.4.1 + * */ virStoragePoolPtr virStoragePoolLookupByVolume(virStorageVolPtr vol) @@ -516,6 +549,9 @@ virStoragePoolLookupByVolume(virStorageVolPtr vol) * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if no matching pool is found + * + * Since: v4.1.0 + * */ virStoragePoolPtr virStoragePoolLookupByTargetPath(virConnectPtr conn, @@ -557,6 +593,9 @@ virStoragePoolLookupByTargetPath(virConnectPtr conn, * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if creation failed + * + * Since: v0.4.1 + * */ virStoragePoolPtr virStoragePoolCreateXML(virConnectPtr conn, @@ -600,6 +639,9 @@ virStoragePoolCreateXML(virConnectPtr conn, * storage pool object is no longer needed. * * Returns a virStoragePoolPtr object, or NULL if creation failed + * + * Since: v0.4.1 + * */ virStoragePoolPtr virStoragePoolDefineXML(virConnectPtr conn, @@ -641,6 +683,9 @@ virStoragePoolDefineXML(virConnectPtr conn, * Build the underlying storage pool * * Returns 0 on success, or -1 upon failure + * + * Since: v0.4.1 + * */ int virStoragePoolBuild(virStoragePoolPtr pool, @@ -679,6 +724,9 @@ virStoragePoolBuild(virStoragePoolPtr pool, * Undefine an inactive storage pool * * Returns 0 on success, -1 on failure + * + * Since: v0.4.1 + * */ int virStoragePoolUndefine(virStoragePoolPtr pool) @@ -717,6 +765,9 @@ virStoragePoolUndefine(virStoragePoolPtr pool) * Starts an inactive storage pool * * Returns 0 on success, or -1 if it could not be started + * + * Since: v0.4.1 + * */ int virStoragePoolCreate(virStoragePoolPtr pool, @@ -759,6 +810,9 @@ virStoragePoolCreate(virStoragePoolPtr pool, * the associated virStoragePoolPtr object. * * Returns 0 on success, or -1 if it could not be destroyed + * + * Since: v0.4.1 + * */ int virStoragePoolDestroy(virStoragePoolPtr pool) @@ -799,6 +853,9 @@ virStoragePoolDestroy(virStoragePoolPtr pool) * itself is not free'd. * * Returns 0 on success, or -1 if it could not be obliterate + * + * Since: v0.4.1 + * */ int virStoragePoolDelete(virStoragePoolPtr pool, @@ -838,6 +895,9 @@ virStoragePoolDelete(virStoragePoolPtr pool, * it. Does not change the state of the pool on the host. * * Returns 0 on success, or -1 if it could not be free'd. + * + * Since: v0.4.1 + * */ int virStoragePoolFree(virStoragePoolPtr pool) @@ -870,6 +930,9 @@ virStoragePoolFree(virStoragePoolPtr pool) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.6.0 + * */ int virStoragePoolRef(virStoragePoolPtr pool) @@ -895,6 +958,9 @@ virStoragePoolRef(virStoragePoolPtr pool) * new devices at the OS layer * * Returns 0 if the volume list was refreshed, -1 on failure + * + * Since: v0.4.1 + * */ int virStoragePoolRefresh(virStoragePoolPtr pool, @@ -933,6 +999,9 @@ virStoragePoolRefresh(virStoragePoolPtr pool, * Fetch the locally unique name of the storage pool * * Returns the name of the pool, or NULL on error + * + * Since: v0.4.1 + * */ const char* virStoragePoolGetName(virStoragePoolPtr pool) @@ -955,6 +1024,9 @@ virStoragePoolGetName(virStoragePoolPtr pool) * Fetch the globally unique ID of the storage pool * * Returns 0 on success, or -1 on error; + * + * Since: v0.4.1 + * */ int virStoragePoolGetUUID(virStoragePoolPtr pool, @@ -985,6 +1057,9 @@ virStoragePoolGetUUID(virStoragePoolPtr pool, * Fetch the globally unique ID of the storage pool as a string * * Returns 0 on success, or -1 on error; + * + * Since: v0.4.1 + * */ int virStoragePoolGetUUIDString(virStoragePoolPtr pool, @@ -1015,6 +1090,9 @@ virStoragePoolGetUUIDString(virStoragePoolPtr pool, * such as free space / usage summary * * Returns 0 on success, or -1 on failure. + * + * Since: v0.4.1 + * */ int virStoragePoolGetInfo(virStoragePoolPtr pool, @@ -1059,6 +1137,9 @@ virStoragePoolGetInfo(virStoragePoolPtr pool, * into the virStoragePoolCreateXML method. * * Returns a XML document (caller frees), or NULL on error + * + * Since: v0.4.1 + * */ char * virStoragePoolGetXMLDesc(virStoragePoolPtr pool, @@ -1097,6 +1178,9 @@ virStoragePoolGetXMLDesc(virStoragePoolPtr pool, * whether the pool is automatically started at boot time * * Returns 0 on success, -1 on failure + * + * Since: v0.4.1 + * */ int virStoragePoolGetAutostart(virStoragePoolPtr pool, @@ -1137,6 +1221,9 @@ virStoragePoolGetAutostart(virStoragePoolPtr pool, * when the host machine boots. * * Returns 0 on success, -1 on failure + * + * Since: v0.4.1 + * */ int virStoragePoolSetAutostart(virStoragePoolPtr pool, @@ -1185,6 +1272,9 @@ virStoragePoolSetAutostart(virStoragePoolPtr pool, * in the return count, to make iteration easier. The caller is responsible * for calling virStorageVolFree() on each array element, then calling * free() on @vols. + * + * Since: v0.10.2 + * */ int virStoragePoolListAllVolumes(virStoragePoolPtr pool, @@ -1221,6 +1311,9 @@ virStoragePoolListAllVolumes(virStoragePoolPtr pool, * Fetch the number of storage volumes within a pool * * Returns the number of storage pools, or -1 on failure + * + * Since: v0.4.1 + * */ int virStoragePoolNumOfVolumes(virStoragePoolPtr pool) @@ -1260,6 +1353,9 @@ virStoragePoolNumOfVolumes(virStoragePoolPtr pool) * virStoragePoolListAllVolumes(). * * Returns the number of names fetched, or -1 on error + * + * Since: v0.4.1 + * */ int virStoragePoolListVolumes(virStoragePoolPtr pool, @@ -1299,6 +1395,9 @@ virStoragePoolListVolumes(virStoragePoolPtr pool, * call. * * Returns the virConnectPtr or NULL in case of failure. + * + * Since: v0.4.1 + * */ virConnectPtr virStorageVolGetConnect(virStorageVolPtr vol) @@ -1325,6 +1424,9 @@ virStorageVolGetConnect(virStorageVolPtr vol) * storage volume object is no longer needed. * * Returns a storage volume, or NULL if not found / error + * + * Since: v0.4.1 + * */ virStorageVolPtr virStorageVolLookupByName(virStoragePoolPtr pool, @@ -1365,6 +1467,9 @@ virStorageVolLookupByName(virStoragePoolPtr pool, * storage volume object is no longer needed. * * Returns a storage volume, or NULL if not found / error + * + * Since: v0.4.1 + * */ virStorageVolPtr virStorageVolLookupByKey(virConnectPtr conn, @@ -1405,6 +1510,9 @@ virStorageVolLookupByKey(virConnectPtr conn, * storage volume object is no longer needed. * * Returns a storage volume, or NULL if not found / error + * + * Since: v0.4.1 + * */ virStorageVolPtr virStorageVolLookupByPath(virConnectPtr conn, @@ -1441,6 +1549,9 @@ virStorageVolLookupByPath(virConnectPtr conn, * within the scope of a pool * * Returns the volume name, or NULL on error + * + * Since: v0.4.1 + * */ const char* virStorageVolGetName(virStorageVolPtr vol) @@ -1464,6 +1575,9 @@ virStorageVolGetName(virStorageVolPtr vol) * key no matter what host it is accessed from * * Returns the volume key, or NULL on error + * + * Since: v0.4.1 + * */ const char* virStorageVolGetKey(virStorageVolPtr vol) @@ -1497,6 +1611,9 @@ virStorageVolGetKey(virStorageVolPtr vol) * storage volume object is no longer needed. * * Returns the storage volume, or NULL on error + * + * Since: v0.4.1 + * */ virStorageVolPtr virStorageVolCreateXML(virStoragePoolPtr pool, @@ -1548,6 +1665,9 @@ virStorageVolCreateXML(virStoragePoolPtr pool, * storage volume object is no longer needed. * * Returns the storage volume, or NULL on error + * + * Since: v0.6.4 + * */ virStorageVolPtr virStorageVolCreateXMLFrom(virStoragePoolPtr pool, @@ -1612,6 +1732,9 @@ virStorageVolCreateXMLFrom(virStoragePoolPtr pool, * another active stream is writing to the storage volume. * * Returns 0, or -1 upon error. + * + * Since: v0.9.0 + * */ int virStorageVolDownload(virStorageVolPtr vol, @@ -1695,6 +1818,9 @@ virStorageVolDownload(virStorageVolPtr vol, * capacity, and allocation. * * Returns 0, or -1 upon error. + * + * Since: v0.9.0 + * */ int virStorageVolUpload(virStorageVolPtr vol, @@ -1748,6 +1874,9 @@ virStorageVolUpload(virStorageVolPtr vol, * Delete the storage volume from the pool * * Returns 0 on success, or -1 on error + * + * Since: v0.4.1 + * */ int virStorageVolDelete(virStorageVolPtr vol, @@ -1797,6 +1926,9 @@ virStorageVolDelete(virStorageVolPtr vol, * network file systems are known to be problematic. * * Returns 0 on success, or -1 on error + * + * Since: v0.8.0 + * */ int virStorageVolWipe(virStorageVolPtr vol, @@ -1843,6 +1975,9 @@ virStorageVolWipe(virStorageVolPtr vol, * problematic. * * Returns 0 on success, or -1 on error. + * + * Since: v0.9.10 + * */ int virStorageVolWipePattern(virStorageVolPtr vol, @@ -1883,6 +2018,9 @@ virStorageVolWipePattern(virStorageVolPtr vol, * storage volume continues to exist. * * Returns 0 on success, or -1 on error + * + * Since: v0.4.1 + * */ int virStorageVolFree(virStorageVolPtr vol) @@ -1914,6 +2052,9 @@ virStorageVolFree(virStorageVolPtr vol) * the reference count. * * Returns 0 in case of success, -1 in case of failure. + * + * Since: v0.6.0 + * */ int virStorageVolRef(virStorageVolPtr vol) @@ -1938,6 +2079,9 @@ virStorageVolRef(virStorageVolPtr vol) * volume such as its current allocation * * Returns 0 on success, or -1 on failure + * + * Since: v0.4.1 + * */ int virStorageVolGetInfo(virStorageVolPtr vol, @@ -1988,6 +2132,9 @@ virStorageVolGetInfo(virStorageVolPtr vol, * as is the case with qcow2 files. * * Returns 0 on success, or -1 on failure + * + * Since: v3.0.0 + * */ int virStorageVolGetInfoFlags(virStorageVolPtr vol, @@ -2032,6 +2179,9 @@ virStorageVolGetInfoFlags(virStorageVolPtr vol, * the storage volume * * Returns the XML document, or NULL on error + * + * Since: v0.4.1 + * */ char * virStorageVolGetXMLDesc(virStorageVolPtr vol, @@ -2073,6 +2223,9 @@ virStorageVolGetXMLDesc(virStorageVolPtr vol, * * Returns the storage volume path, or NULL on error. The * caller must free() the returned path after use. + * + * Since: v0.4.1 + * */ char * virStorageVolGetPath(virStorageVolPtr vol) @@ -2134,6 +2287,9 @@ virStorageVolGetPath(virStorageVolPtr vol) * than the current size. * * Returns 0 on success, or -1 on error. + * + * Since: v0.9.10 + * */ int virStorageVolResize(virStorageVolPtr vol, @@ -2183,6 +2339,9 @@ virStorageVolResize(virStorageVolPtr vol, * Determine if the storage pool is currently running * * Returns 1 if running, 0 if inactive, -1 on error + * + * Since: v0.7.3 + * */ int virStoragePoolIsActive(virStoragePoolPtr pool) @@ -2216,6 +2375,9 @@ virStoragePoolIsActive(virStoragePoolPtr pool) * which means it will still exist after shutting down * * Returns 1 if persistent, 0 if transient, -1 on error + * + * Since: v0.7.3 + * */ int virStoragePoolIsPersistent(virStoragePoolPtr pool) @@ -2274,6 +2436,9 @@ virStoragePoolIsPersistent(virStoragePoolPtr pool) * be passed to the virConnectStoragePoolEventDeregisterAny() method. * * Returns a callback identifier on success, -1 on failure. + * + * Since: v2.0.0 + * */ int virConnectStoragePoolEventRegisterAny(virConnectPtr conn, @@ -2337,6 +2502,9 @@ virConnectStoragePoolEventRegisterAny(virConnectPtr conn, * value obtained from a previous virConnectStoragePoolEventRegisterAny() method. * * Returns 0 on success, -1 on failure + * + * Since: v2.0.0 + * */ int virConnectStoragePoolEventDeregisterAny(virConnectPtr conn, @@ -2376,6 +2544,9 @@ virConnectStoragePoolEventDeregisterAny(virConnectPtr conn, * are supported along with the file/disk formats for each pool. * * Returns NULL in case of error or an XML string defining the capabilities. + * + * Since: v5.2.0 + * */ char * virConnectGetStoragePoolCapabilities(virConnectPtr conn, diff --git a/src/libvirt-stream.c b/src/libvirt-stream.c index 80dbc83a59..35beb67a10 100644 --- a/src/libvirt-stream.c +++ b/src/libvirt-stream.c @@ -52,6 +52,9 @@ VIR_LOG_INIT("libvirt.stream"); * VIR_STREAM_NONBLOCK for flags, otherwise pass 0. * * Returns the new stream, or NULL upon error + * + * Since: v0.7.2 + * */ virStreamPtr virStreamNew(virConnectPtr conn, @@ -85,6 +88,9 @@ virStreamNew(virConnectPtr conn, * the caller no longer needs the reference to this object. * * Returns 0 in case of success, -1 in case of failure + * + * Since: v0.7.2 + * */ int virStreamRef(virStreamPtr stream) @@ -163,6 +169,9 @@ virStreamRef(virStreamPtr stream) * * Returns -2 if the outgoing transmit buffers are full & * the stream is marked as non-blocking. + * + * Since: v0.7.2 + * */ int virStreamSend(virStreamPtr stream, @@ -258,6 +267,9 @@ virStreamSend(virStreamPtr stream, * * Returns -2 if there is no data pending to be read & the * stream is marked as non-blocking. + * + * Since: v0.7.2 + * */ int virStreamRecv(virStreamPtr stream, @@ -345,6 +357,9 @@ virStreamRecv(virStreamPtr stream, * * Returns -3 if there is a hole in stream and caller requested * to stop at a hole. + * + * Since: v3.4.0 + * */ int virStreamRecvFlags(virStreamPtr stream, @@ -412,6 +427,9 @@ virStreamRecvFlags(virStreamPtr stream, * * Returns 0 on success, * -1 error + * + * Since: v3.4.0 + * */ int virStreamSendHole(virStreamPtr stream, @@ -455,6 +473,9 @@ virStreamSendHole(virStreamPtr stream, * * Returns 0 on success, * -1 on error or when there's currently no hole in the stream + * + * Since: v3.4.0 + * */ int virStreamRecvHole(virStreamPtr stream, @@ -577,6 +598,9 @@ virStreamInData(virStreamPtr stream, * Returns -1 upon any error, with virStreamAbort() already * having been called, so the caller need only call * virStreamFree(). + * + * Since: v0.7.2 + * */ int virStreamSendAll(virStreamPtr stream, @@ -706,6 +730,9 @@ virStreamSendAll(virStreamPtr stream, * Returns -1 upon any error, with virStreamAbort() already * having been called, so the caller need only call * virStreamFree(). + * + * Since: v3.4.0 + * */ int virStreamSparseSendAll(virStreamPtr stream, virStreamSourceFunc handler, @@ -845,6 +872,9 @@ int virStreamSparseSendAll(virStreamPtr stream, * Returns -1 upon any error, with virStreamAbort() already * having been called, so the caller need only call * virStreamFree() + * + * Since: v0.7.2 + * */ int virStreamRecvAll(virStreamPtr stream, @@ -958,6 +988,9 @@ virStreamRecvAll(virStreamPtr stream, * * Returns -1 upon any error, with virStreamAbort() already * having been called, so the caller need only call virStreamFree(). + * + * Since: v3.4.0 + * */ int virStreamSparseRecvAll(virStreamPtr stream, @@ -1051,6 +1084,9 @@ virStreamSparseRecvAll(virStreamPtr stream, * to integrate into an event loop * * Returns 0 on success, -1 upon error + * + * Since: v0.7.2 + * */ int virStreamEventAddCallback(virStreamPtr stream, @@ -1094,6 +1130,9 @@ virStreamEventAddCallback(virStreamPtr stream, * is guaranteed to succeed if a callback is already registered * * Returns 0 on success, -1 if no callback is registered + * + * Since: v0.7.2 + * */ int virStreamEventUpdateCallback(virStreamPtr stream, @@ -1129,6 +1168,9 @@ virStreamEventUpdateCallback(virStreamPtr stream, * Remove an event callback from the stream * * Returns 0 on success, -1 on error + * + * Since: v0.7.2 + * */ int virStreamEventRemoveCallback(virStreamPtr stream) @@ -1173,6 +1215,9 @@ virStreamEventRemoveCallback(virStreamPtr stream) * beforehand. * * Returns 0 on success, -1 upon error + * + * Since: v0.7.2 + * */ int virStreamFinish(virStreamPtr stream) @@ -1215,6 +1260,9 @@ virStreamFinish(virStreamPtr stream) * beforehand. * * Returns 0 on success, -1 upon error + * + * Since: v0.7.2 + * */ int virStreamAbort(virStreamPtr stream) @@ -1259,6 +1307,9 @@ virStreamAbort(virStreamPtr stream) * the virStreamAbort function should be called first. * * Returns 0 upon success, or -1 on error + * + * Since: v0.7.2 + * */ int virStreamFree(virStreamPtr stream) diff --git a/src/libvirt.c b/src/libvirt.c index 6cda75d1ca..0c8e787920 100644 --- a/src/libvirt.c +++ b/src/libvirt.c @@ -296,6 +296,9 @@ virGlobalInit(void) * connection attempt. * * Returns 0 in case of success, -1 in case of error + * + * Since: v0.1.0 + * */ int virInitialize(void) @@ -797,6 +800,9 @@ virStateStop(void) * * Returns -1 in case of failure, 0 otherwise, and values for @libVer and * @typeVer have the format major * 1,000,000 + minor * 1,000 + release. + * + * Since: v0.0.1 + * */ int virGetVersion(unsigned long *libVer, const char *type G_GNUC_UNUSED, @@ -1185,6 +1191,9 @@ virConnectOpenInternal(const char *name, * is no longer needed. * * Returns a pointer to the hypervisor connection or NULL in case of error + * + * Since: v0.0.1 + * */ virConnectPtr virConnectOpen(const char *name) @@ -1218,6 +1227,9 @@ virConnectOpen(const char *name) * URIs are documented at https://libvirt.org/uri.html * * Returns a pointer to the hypervisor connection or NULL in case of error + * + * Since: v0.0.1 + * */ virConnectPtr virConnectOpenReadOnly(const char *name) @@ -1252,6 +1264,9 @@ virConnectOpenReadOnly(const char *name) * URIs are documented at https://libvirt.org/uri.html * * Returns a pointer to the hypervisor connection or NULL in case of error + * + * Since: v0.4.1 + * */ virConnectPtr virConnectOpenAuth(const char *name, @@ -1300,6 +1315,9 @@ virConnectOpenAuth(const char *name, * value if some other object still has a temporary reference to the * connection, but the application should not try to further use a * connection after the virConnectClose that matches the initial open. + * + * Since: v0.0.1 + * */ int virConnectClose(virConnectPtr conn) diff --git a/src/util/virerror.c b/src/util/virerror.c index e864a50fba..7d009d2298 100644 --- a/src/util/virerror.c +++ b/src/util/virerror.c @@ -254,6 +254,9 @@ virLastErrorObject(void) * threads can safely access this concurrently. * * Returns a pointer to the last error or NULL if none occurred. + * + * Since: v0.1.0 + * */ virErrorPtr virGetLastError(void) @@ -271,6 +274,9 @@ virGetLastError(void) * Get the most recent error code (enum virErrorNumber). * * Returns the most recent error code, or VIR_ERR_OK if none is set. + * + * Since: v4.5.0 + * */ int virGetLastErrorCode(void) @@ -289,6 +295,9 @@ virGetLastErrorCode(void) * * Returns a numerical value of the most recent error's origin, or VIR_FROM_NONE * if none is set. + * + * Since: v4.5.0 + * */ int virGetLastErrorDomain(void) @@ -307,6 +316,9 @@ virGetLastErrorDomain(void) * * Returns the most recent error message string in this * thread, or a generic message if none is set + * + * Since: v1.0.5.2 + * */ const char * virGetLastErrorMessage(void) @@ -361,6 +373,9 @@ virSetError(virErrorPtr newerr) * One will need to free the result with virResetError() * * Returns error code or -1 in case of parameter error. + * + * Since: v0.1.0 + * */ int virCopyLastError(virErrorPtr to) @@ -392,6 +407,9 @@ virCopyLastError(virErrorPtr to) * Returns a pointer to the copied error or NULL if allocation failed. * It is the caller's responsibility to free the error with * virFreeError(). + * + * Since: v0.6.1 + * */ virErrorPtr virSaveLastError(void) @@ -455,6 +473,9 @@ virErrorRestore(virErrorPtr *savederr) * @err: pointer to the virError to clean up * * Reset the error being pointed to + * + * Since: v0.1.0 + * */ void virResetError(virErrorPtr err) @@ -473,6 +494,9 @@ virResetError(virErrorPtr err) * @err: error to free * * Resets and frees the given error. + * + * Since: v0.6.1 + * */ void virFreeError(virErrorPtr err) @@ -489,6 +513,9 @@ virFreeError(virErrorPtr err) * The error object is kept in thread local storage, so separate * threads can safely access this concurrently, only resetting * their own error object. + * + * Since: v0.1.0 + * */ void virResetLastError(void) @@ -519,6 +546,9 @@ virResetLastError(void) * remains for backwards compatibility. * * Returns a pointer to the last error or NULL if none occurred. + * + * Since: v0.1.0 + * */ virErrorPtr virConnGetLastError(virConnectPtr conn) @@ -553,6 +583,9 @@ virConnGetLastError(virConnectPtr conn) * * Returns 0 if no error was found and the error code otherwise and -1 in case * of parameter error. + * + * Since: v0.1.0 + * */ int virConnCopyLastError(virConnectPtr conn, virErrorPtr to) @@ -579,6 +612,9 @@ virConnCopyLastError(virConnectPtr conn, virErrorPtr to) * threads can safely access this concurrently. * * Reset the last error caught on that connection + * + * Since: v0.1.0 + * */ void virConnResetLastError(virConnectPtr conn) @@ -598,6 +634,9 @@ virConnResetLastError(virConnectPtr conn) * Set a library global error handling function, if @handler is NULL, * it will reset to default printing on stderr. The error raised there * are those for which no handler at the connection level could caught. + * + * Since: v0.1.0 + * */ void virSetErrorFunc(void *userData, virErrorFunc handler) @@ -615,6 +654,9 @@ virSetErrorFunc(void *userData, virErrorFunc handler) * Set a connection error handling function, if @handler is NULL * it will reset to default which is to pass error back to the global * library handler. + * + * Since: v0.1.0 + * */ void virConnSetErrorFunc(virConnectPtr conn, void *userData, @@ -633,6 +675,9 @@ virConnSetErrorFunc(virConnectPtr conn, void *userData, * @err: pointer to the error. * * Default routine reporting an error to stderr. + * + * Since: v0.1.0 + * */ void virDefaultErrorFunc(virErrorPtr err) diff --git a/src/util/virevent.c b/src/util/virevent.c index f6eb806faf..6914901507 100644 --- a/src/util/virevent.c +++ b/src/util/virevent.c @@ -69,6 +69,9 @@ static virEventRemoveTimeoutFunc removeTimeoutImpl; * * Returns -1 if the file handle cannot be registered, otherwise a handle * watch number to be used for updating and unregistering for events. + * + * Since: v0.9.3 + * */ int virEventAddHandle(int fd, @@ -94,6 +97,9 @@ virEventAddHandle(int fd, * virEventRegisterImpl() or virEventRegisterDefaultImpl(). * * Will not fail if fd exists. + * + * Since: v0.9.3 + * */ void virEventUpdateHandle(int watch, int events) @@ -112,6 +118,9 @@ virEventUpdateHandle(int watch, int events) * virEventRegisterImpl() or virEventRegisterDefaultImpl(). * * Returns -1 if the file handle was not registered, 0 upon success. + * + * Since: v0.9.3 + * */ int virEventRemoveHandle(int watch) @@ -139,6 +148,9 @@ virEventRemoveHandle(int watch) * * Returns -1 if the timer cannot be registered, a positive * integer timer id upon success. + * + * Since: v0.9.3 + * */ int virEventAddTimeout(int timeout, @@ -166,6 +178,9 @@ virEventAddTimeout(int timeout, * to zero will cause it to fire on every event loop iteration. * * Will not fail if timer exists. + * + * Since: v0.9.3 + * */ void virEventUpdateTimeout(int timer, int timeout) @@ -184,6 +199,9 @@ virEventUpdateTimeout(int timer, int timeout) * virEventRegisterImpl() or virEventRegisterDefaultImpl(). * * Returns -1 if the timer was not registered, 0 upon success. + * + * Since: v0.9.3 + * */ int virEventRemoveTimeout(int timer) @@ -232,6 +250,9 @@ virEventRemoveTimeout(int timer) * virConnectClose on all open connections, so it is not safe * to stop running the event loop immediately after closing * the connection. + * + * Since: v0.5.0 + * */ void virEventRegisterImpl(virEventAddHandleFunc addHandle, virEventUpdateHandleFunc updateHandle, @@ -300,6 +321,9 @@ int virEventRequireImpl(void) * virEventAddHandle() or virConnectDomainEventRegisterAny(). * * Returns 0 on success, -1 on failure. + * + * Since: v0.9.0 + * */ int virEventRegisterDefaultImpl(void) { @@ -335,6 +359,9 @@ int virEventRegisterDefaultImpl(void) * } * * Returns 0 on success, -1 on failure. + * + * Since: v0.9.0 + * */ int virEventRunDefaultImpl(void) { -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given function was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso@redhat.com> --- include/libvirt/libvirt-qemu.h | 3 +++ src/libvirt-qemu.c | 18 ++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/include/libvirt/libvirt-qemu.h b/include/libvirt/libvirt-qemu.h index 9697b54158..fb422a3a21 100644 --- a/include/libvirt/libvirt-qemu.h +++ b/include/libvirt/libvirt-qemu.h @@ -86,6 +86,9 @@ char *virDomainQemuAgentCommand(virDomainPtr domain, const char *cmd, * * The callback signature to use when registering for a qemu monitor * event with virConnectDomainQemuMonitorEventRegister(). + * + * Since: v1.2.3 + * */ typedef void (*virConnectDomainQemuMonitorEventCallback)(virConnectPtr conn, virDomainPtr dom, diff --git a/src/libvirt-qemu.c b/src/libvirt-qemu.c index 896aba2f0b..b80cd2b7ff 100644 --- a/src/libvirt-qemu.c +++ b/src/libvirt-qemu.c @@ -61,6 +61,9 @@ VIR_LOG_INIT("libvirt-qemu"); * * Returns 0 in case of success, -1 in case of failure * + * Since: v0.8.3 + * + * */ int virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd, @@ -131,6 +134,9 @@ virDomainQemuMonitorCommand(virDomainPtr domain, const char *cmd, * @cmd, and the caller must free this string. * * Returns 0 in case of success, -1 in case of failure + * + * Since: v8.2.0 + * */ int virDomainQemuMonitorCommandWithFiles(virDomainPtr domain, @@ -216,6 +222,9 @@ virDomainQemuMonitorCommandWithFiles(virDomainPtr domain, * normally (provided the above requirements were honored). * * Returns a new domain object on success, NULL otherwise + * + * Since: v0.9.4 + * */ virDomainPtr virDomainQemuAttach(virConnectPtr conn, @@ -272,6 +281,9 @@ virDomainQemuAttach(virConnectPtr conn, * positive value: wait for @timeout seconds * * Returns strings if success, NULL in failure. + * + * Since: v0.10.0 + * */ char * virDomainQemuAgentCommand(virDomainPtr domain, @@ -350,6 +362,9 @@ virDomainQemuAgentCommand(virDomainPtr domain, * be passed to the virConnectDomainQemuMonitorEventDeregister() method. * * Returns a callback identifier on success, -1 on failure + * + * Since: v1.2.3 + * */ int virConnectDomainQemuMonitorEventRegister(virConnectPtr conn, @@ -404,6 +419,9 @@ virConnectDomainQemuMonitorEventRegister(virConnectPtr conn, * method. * * Returns 0 on success, -1 on failure + * + * Since: v1.2.3 + * */ int virConnectDomainQemuMonitorEventDeregister(virConnectPtr conn, -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given function was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso@redhat.com> --- src/libvirt-lxc.c | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/libvirt-lxc.c b/src/libvirt-lxc.c index 2a271b74f0..14a2f2a6ec 100644 --- a/src/libvirt-lxc.c +++ b/src/libvirt-lxc.c @@ -59,6 +59,9 @@ VIR_LOG_INIT("libvirt-lxc"); * the setns() system call. * * Returns the number of opened file descriptors, or -1 on error + * + * Since: v1.0.2 + * */ int virDomainLxcOpenNamespace(virDomainPtr domain, @@ -115,6 +118,9 @@ virDomainLxcOpenNamespace(virDomainPtr domain, * the caller to switch back to its current namespace later * * Returns 0 on success, -1 on error + * + * Since: v1.0.2 + * */ int virDomainLxcEnterNamespace(virDomainPtr domain, @@ -182,6 +188,9 @@ virDomainLxcEnterNamespace(virDomainPtr domain, * exec() has yet been performed. * * Returns 0 on success, -1 on error + * + * Since: v1.0.4 + * */ int virDomainLxcEnterSecurityLabel(virSecurityModelPtr model, @@ -283,6 +292,9 @@ virDomainLxcEnterSecurityLabel(virSecurityModelPtr model, * with the container @domain. * * Returns 0 on success, -1 on error + * + * Since: v2.0.0 + * */ int virDomainLxcEnterCGroup(virDomainPtr domain, unsigned int flags) -- 2.35.1

Either create or append to existing docstring, the version (git tag) that a given function was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso@redhat.com> --- include/libvirt/libvirt-admin.h | 3 ++ src/admin/libvirt-admin.c | 93 +++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+) diff --git a/include/libvirt/libvirt-admin.h b/include/libvirt/libvirt-admin.h index c73cf6e7da..5945fc172c 100644 --- a/include/libvirt/libvirt-admin.h +++ b/include/libvirt/libvirt-admin.h @@ -126,6 +126,9 @@ int virAdmConnectGetLibVersion(virAdmConnectPtr conn, * @opaque: opaque client data * * A callback to be registered, in case a connection was closed. + * + * Since: v1.3.1 + * */ typedef void (*virAdmConnectCloseFunc)(virAdmConnectPtr conn, int reason, diff --git a/src/admin/libvirt-admin.c b/src/admin/libvirt-admin.c index 01546a7bc2..35470c866e 100644 --- a/src/admin/libvirt-admin.c +++ b/src/admin/libvirt-admin.c @@ -84,6 +84,9 @@ virAdmGlobalInit(void) * necessary for the application to call virAdmInitialize. * * Returns 0 in case of success, -1 in case of error + * + * Since: v2.0.0 + * */ int virAdmInitialize(void) @@ -200,6 +203,9 @@ virAdmGetDefaultURI(virConf *conf, char **uristr) * Opens connection to admin interface of the daemon. * * Returns @virAdmConnectPtr object or NULL on error + * + * Since: v1.2.17 + * */ virAdmConnectPtr virAdmConnectOpen(const char *name, unsigned int flags) @@ -284,6 +290,9 @@ virAdmConnectOpen(const char *name, unsigned int flags) * some other object still has a temporary reference to the connection, but the * application should not try to further use a connection after the * virAdmConnectClose that matches the initial open. + * + * Since: v1.2.17 + * */ int virAdmConnectClose(virAdmConnectPtr conn) @@ -319,6 +328,9 @@ virAdmConnectClose(virAdmConnectPtr conn) * would increment the reference count. * * Returns 0 in case of success, -1 in case of failure + * + * Since: v1.2.17 + * */ int virAdmConnectRef(virAdmConnectPtr conn) @@ -346,6 +358,9 @@ virAdmConnectRef(virAdmConnectPtr conn) * instead. * * Returns 0 on success, -1 in case of an error. + * + * Since: v1.3.0 + * */ int virAdmGetVersion(unsigned long long *libVer) @@ -377,6 +392,9 @@ virAdmGetVersion(unsigned long long *libVer) * * Returns 1, if the connection is alive, 0 if there isn't an existing * connection at all or the channel has already been closed, or -1 on error. + * + * Since: v1.3.1 + * */ int virAdmConnectIsAlive(virAdmConnectPtr conn) @@ -411,6 +429,9 @@ virAdmConnectIsAlive(virAdmConnectPtr conn) * * Returns an URI string related to the connection or NULL in case of an error. * Caller is responsible for freeing the string. + * + * Since: v1.3.1 + * */ char * virAdmConnectGetURI(virAdmConnectPtr conn) @@ -445,6 +466,9 @@ virAdmConnectGetURI(virAdmConnectPtr conn) * context. * * Returns 0 on success, -1 on error + * + * Since: v1.3.1 + * */ int virAdmConnectRegisterCloseCallback(virAdmConnectPtr conn, virAdmConnectCloseFunc cb, @@ -498,6 +522,9 @@ int virAdmConnectRegisterCloseCallback(virAdmConnectPtr conn, * registration, it will be invoked. * * Returns 0 on success, -1 on error + * + * Since: v1.3.1 + * */ int virAdmConnectUnregisterCloseCallback(virAdmConnectPtr conn, virAdmConnectCloseFunc cb) @@ -528,6 +555,9 @@ int virAdmConnectUnregisterCloseCallback(virAdmConnectPtr conn, * major * 1,000,000 + minor * 1,000 + release. * * Returns 0 on success, -1 on failure and @libVer follows this format: + * + * Since: v1.3.1 + * */ int virAdmConnectGetLibVersion(virAdmConnectPtr conn, unsigned long long *libVer) @@ -556,6 +586,9 @@ int virAdmConnectGetLibVersion(virAdmConnectPtr conn, * * Returns a pointer to the name or NULL. The string doesn't need to be * deallocated since its lifetime will be the same as the server object. + * + * Since: v1.3.2 + * */ const char * virAdmServerGetName(virAdmServerPtr srv) @@ -576,6 +609,9 @@ virAdmServerGetName(virAdmServerPtr srv) * The data structure is freed and should not be used thereafter. * * Returns 0 on success, -1 on failure. + * + * Since: v1.3.2 + * */ int virAdmServerFree(virAdmServerPtr srv) { @@ -599,6 +635,9 @@ int virAdmServerFree(virAdmServerPtr srv) * Get client's unique numeric ID. * * Returns numeric value used for client's ID or -1 in case of an error. + * + * Since: v1.3.5 + * */ unsigned long long virAdmClientGetID(virAdmClientPtr client) @@ -622,6 +661,9 @@ virAdmClientGetID(virAdmClientPtr client) * Returns client's connection timestamp (seconds from epoch in UTC) or 0 * (epoch time) if libvirt doesn't have any information about client's * connection time, or -1 in case of an error. + * + * Since: v1.3.5 + * */ long long virAdmClientGetTimestamp(virAdmClientPtr client) @@ -647,6 +689,9 @@ virAdmClientGetTimestamp(virAdmClientPtr client) * * Returns integer representation of the connection transport used by @client * (this will be one of virClientTransport) or -1 in case of an error. + * + * Since: v1.3.5 + * */ int virAdmClientGetTransport(virAdmClientPtr client) @@ -666,6 +711,9 @@ virAdmClientGetTransport(virAdmClientPtr client) * structure is freed and should not be used thereafter. * * Returns 0 in success, -1 on failure. + * + * Since: v1.3.5 + * */ int virAdmClientFree(virAdmClientPtr client) { @@ -697,6 +745,9 @@ int virAdmClientFree(virAdmClientPtr client) * this extra element from the final count. * Caller is responsible to call virAdmServerFree() on each list element, * followed by freeing @servers. + * + * Since: v1.3.2 + * */ int virAdmConnectListServers(virAdmConnectPtr conn, @@ -735,6 +786,9 @@ virAdmConnectListServers(virAdmConnectPtr conn, * * Returns the requested server or NULL in case of failure. If the * server cannot be found, then VIR_ERR_NO_SERVER error is raised. + * + * Since: v1.3.3 + * */ virAdmServerPtr virAdmConnectLookupServer(virAdmConnectPtr conn, @@ -776,6 +830,9 @@ virAdmConnectLookupServer(virAdmConnectPtr conn, * VIR_THREADPOOL_WORKERS_CURRENT * * Returns 0 on success, -1 in case of an error. + * + * Since: v1.3.4 + * */ int virAdmServerGetThreadPoolParameters(virAdmServerPtr srv, @@ -815,6 +872,9 @@ virAdmServerGetThreadPoolParameters(virAdmServerPtr srv, * failure. * * Returns 0 on success, -1 in case of an error. + * + * Since: v1.3.4 + * */ int virAdmServerSetThreadPoolParameters(virAdmServerPtr srv, @@ -856,6 +916,9 @@ virAdmServerSetThreadPoolParameters(virAdmServerPtr srv, * excluding this extra element from the final count. * Caller is responsible to call virAdmClientFree() on each list element, * followed by freeing @clients. + * + * Since: v1.3.5 + * */ int virAdmServerListClients(virAdmServerPtr srv, @@ -894,6 +957,9 @@ virAdmServerListClients(virAdmServerPtr srv, * * Returns the requested client or NULL in case of failure. If the * client could not be found, then VIR_ERR_NO_CLIENT error is raised. + * + * Since: v1.3.5 + * */ virAdmClientPtr virAdmServerLookupClient(virAdmServerPtr srv, @@ -940,6 +1006,9 @@ virAdmServerLookupClient(virAdmServerPtr srv, * * Returns 0 if the information has been successfully retrieved or -1 in case * of an error. + * + * Since: v1.3.5 + * */ int virAdmClientGetInfo(virAdmClientPtr client, @@ -974,6 +1043,9 @@ virAdmClientGetInfo(virAdmClientPtr client, * * Returns 0 if the daemon's connection with @client was closed successfully * or -1 in case of an error. + * + * Since: v1.3.5 + * */ int virAdmClientClose(virAdmClientPtr client, unsigned int flags) @@ -1011,6 +1083,9 @@ int virAdmClientClose(virAdmClientPtr client, * * Returns 0 on success, allocating @params to size returned in @nparams, or * -1 in case of an error. Caller is responsible for deallocating @params. + * + * Since: v1.3.5 + * */ int virAdmServerGetClientLimits(virAdmServerPtr srv, @@ -1051,6 +1126,9 @@ virAdmServerGetClientLimits(virAdmServerPtr srv, * * Returns 0 if the limits have been changed successfully or -1 in case of an * error. + * + * Since: v1.3.5 + * */ int virAdmServerSetClientLimits(virAdmServerPtr srv, @@ -1089,6 +1167,9 @@ virAdmServerSetClientLimits(virAdmServerPtr srv, * * Returns 0 if the TLS files have been updated successfully or -1 in case of an * error. + * + * Since: v6.2.0 + * */ int virAdmServerUpdateTlsFiles(virAdmServerPtr srv, @@ -1127,6 +1208,9 @@ virAdmServerUpdateTlsFiles(virAdmServerPtr srv, * caller. Caller is also responsible for freeing @outputs correctly. * * Returns the count of outputs in @outputs, or -1 in case of an error. + * + * Since: v3.0.0 + * */ int virAdmConnectGetLoggingOutputs(virAdmConnectPtr conn, @@ -1168,6 +1252,9 @@ virAdmConnectGetLoggingOutputs(virAdmConnectPtr conn, * * Returns the number of filters returned in @filters, or -1 in case of * an error. + * + * Since: v3.0.0 + * */ int virAdmConnectGetLoggingFilters(virAdmConnectPtr conn, @@ -1208,6 +1295,9 @@ virAdmConnectGetLoggingFilters(virAdmConnectPtr conn, * * Returns 0 if the new output or the set of outputs has been defined * successfully, or -1 in case of an error. + * + * Since: v3.0.0 + * */ int virAdmConnectSetLoggingOutputs(virAdmConnectPtr conn, @@ -1246,6 +1336,9 @@ virAdmConnectSetLoggingOutputs(virAdmConnectPtr conn, * * Returns 0 if the new filter or the set of filters has been defined * successfully, or -1 in case of an error. + * + * Since: v3.0.0 + * */ int virAdmConnectSetLoggingFilters(virAdmConnectPtr conn, -- 2.35.1

Similarly to previous commits but with the targeting libvirt-common in a batch. Either create or append to existing docstring, the version (git tag) that a given typedef, enum value, macro or function was introduced in the format: Since: v1.2.3 Signed-off-by: Victor Toso <victortoso@redhat.com> --- include/libvirt/libvirt-common.h.in | 54 ++++++++++++++++++++------- src/util/virtypedparam-public.c | 57 +++++++++++++++++++++++++++++ 2 files changed, 98 insertions(+), 13 deletions(-) diff --git a/include/libvirt/libvirt-common.h.in b/include/libvirt/libvirt-common.h.in index 4661ee9857..c2426809b6 100644 --- a/include/libvirt/libvirt-common.h.in +++ b/include/libvirt/libvirt-common.h.in @@ -70,6 +70,8 @@ extern "C" { * * Macro providing the version of the library as * version * 1,000,000 + minor * 1000 + micro + * + * Since: v0.0.1 */ # define LIBVIR_VERSION_NUMBER @LIBVIRT_VERSION_NUMBER@ @@ -86,6 +88,8 @@ extern "C" { * #if LIBVIR_CHECK_VERSION(1,1,3) * // some code that only works in 1.1.3 and newer * #endif + * + * Since: v1.2.0 */ # define LIBVIR_CHECK_VERSION(major, minor, micro) \ ((major) * 1000000 + (minor) * 1000 + (micro) <= LIBVIR_VERSION_NUMBER) @@ -104,17 +108,26 @@ extern "C" { * from a context which is not re-entrant safe. Failure to * abide by this requirement may lead to application deadlocks * or crashes. + * + * Since: v0.5.0 + * */ typedef void (*virFreeCallback)(void *opaque); +/** + * virConnectCloseReason: + * + * Since: v0.10.0 + * + */ typedef enum { - VIR_CONNECT_CLOSE_REASON_ERROR = 0, /* Misc I/O error */ - VIR_CONNECT_CLOSE_REASON_EOF = 1, /* End-of-file from server */ - VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2, /* Keepalive timer triggered */ - VIR_CONNECT_CLOSE_REASON_CLIENT = 3, /* Client requested it */ + VIR_CONNECT_CLOSE_REASON_ERROR = 0, /* Misc I/O error (Since: v0.10.0) */ + VIR_CONNECT_CLOSE_REASON_EOF = 1, /* End-of-file from server (Since: v0.10.0) */ + VIR_CONNECT_CLOSE_REASON_KEEPALIVE = 2, /* Keepalive timer triggered (Since: v0.10.0) */ + VIR_CONNECT_CLOSE_REASON_CLIENT = 3, /* Client requested it (Since: v0.10.0) */ # ifdef VIR_ENUM_SENTINELS - VIR_CONNECT_CLOSE_REASON_LAST + VIR_CONNECT_CLOSE_REASON_LAST /* (Since: v0.10.0) */ # endif } virConnectCloseReason; @@ -122,18 +135,20 @@ typedef enum { * virTypedParameterType: * * Express the type of a virTypedParameter + * + * Since: v0.9.2 */ typedef enum { - VIR_TYPED_PARAM_INT = 1, /* integer case */ - VIR_TYPED_PARAM_UINT = 2, /* unsigned integer case */ - VIR_TYPED_PARAM_LLONG = 3, /* long long case */ - VIR_TYPED_PARAM_ULLONG = 4, /* unsigned long long case */ - VIR_TYPED_PARAM_DOUBLE = 5, /* double case */ - VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case */ - VIR_TYPED_PARAM_STRING = 7, /* string case */ + VIR_TYPED_PARAM_INT = 1, /* integer case (Since: v0.9.2) */ + VIR_TYPED_PARAM_UINT = 2, /* unsigned integer case (Since: v0.9.2) */ + VIR_TYPED_PARAM_LLONG = 3, /* long long case (Since: v0.9.2) */ + VIR_TYPED_PARAM_ULLONG = 4, /* unsigned long long case (Since: v0.9.2) */ + VIR_TYPED_PARAM_DOUBLE = 5, /* double case (Since: v0.9.2) */ + VIR_TYPED_PARAM_BOOLEAN = 6, /* boolean(character) case (Since: v0.9.2) */ + VIR_TYPED_PARAM_STRING = 7, /* string case (Since: v0.9.8) */ # ifdef VIR_ENUM_SENTINELS - VIR_TYPED_PARAM_LAST + VIR_TYPED_PARAM_LAST /* (Since: v0.9.10) */ # endif } virTypedParameterType; @@ -143,6 +158,8 @@ typedef enum { * Flags related to libvirt APIs that use virTypedParameter. * * These enums should not conflict with those of virDomainModificationImpact. + * + * Since: v0.9.8 */ typedef enum { /* 1 << 0 is reserved for virDomainModificationImpact */ @@ -157,6 +174,8 @@ typedef enum { * the user does not have to worry about it; however, manually * setting the flag can be used to reject servers that cannot * return typed strings, even if no strings would be returned. + * + * Since: v0.9.8 */ VIR_TYPED_PARAM_STRING_OKAY = 1 << 2, @@ -166,6 +185,9 @@ typedef enum { * VIR_TYPED_PARAM_FIELD_LENGTH: * * Macro providing the field length of virTypedParameter name + * + * Since: v0.9.2 + * */ # define VIR_TYPED_PARAM_FIELD_LENGTH 80 @@ -177,6 +199,9 @@ typedef enum { * The types virSchedParameter, virBlkioParameter, and * virMemoryParameter are aliases of this type, for use when * targeting libvirt earlier than 0.9.2. + * + * Since: v0.9.2 + * */ typedef struct _virTypedParameter virTypedParameter; @@ -198,6 +223,9 @@ struct _virTypedParameter { * virTypedParameterPtr: * * a pointer to a virTypedParameter structure. + * + * Since: v0.9.2 + * */ typedef virTypedParameter *virTypedParameterPtr; diff --git a/src/util/virtypedparam-public.c b/src/util/virtypedparam-public.c index 4cb54f7ab1..2e213f2ace 100644 --- a/src/util/virtypedparam-public.c +++ b/src/util/virtypedparam-public.c @@ -127,6 +127,9 @@ virTypedParameterAssignFromStr(virTypedParameterPtr param, * * Returns pointer to the parameter or NULL if it does not exist in @params. * This function does not raise an error, even when returning NULL. + * + * Since: v1.0.2 + * */ virTypedParameterPtr virTypedParamsGet(virTypedParameterPtr params, @@ -176,6 +179,9 @@ virTypedParamsGet(virTypedParameterPtr params, * * Returns 1 on success, 0 when the parameter does not exist in @params, or * -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsGetInt(virTypedParameterPtr params, @@ -212,6 +218,9 @@ virTypedParamsGetInt(virTypedParameterPtr params, * * Returns 1 on success, 0 when the parameter does not exist in @params, or * -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsGetUInt(virTypedParameterPtr params, @@ -248,6 +257,9 @@ virTypedParamsGetUInt(virTypedParameterPtr params, * * Returns 1 on success, 0 when the parameter does not exist in @params, or * -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsGetLLong(virTypedParameterPtr params, @@ -284,6 +296,9 @@ virTypedParamsGetLLong(virTypedParameterPtr params, * * Returns 1 on success, 0 when the parameter does not exist in @params, or * -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsGetULLong(virTypedParameterPtr params, @@ -320,6 +335,9 @@ virTypedParamsGetULLong(virTypedParameterPtr params, * * Returns 1 on success, 0 when the parameter does not exist in @params, or * -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsGetDouble(virTypedParameterPtr params, @@ -356,6 +374,9 @@ virTypedParamsGetDouble(virTypedParameterPtr params, * * Returns 1 on success, 0 when the parameter does not exist in @params, or * -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsGetBoolean(virTypedParameterPtr params, @@ -394,6 +415,9 @@ virTypedParamsGetBoolean(virTypedParameterPtr params, * * Returns 1 on success, 0 when the parameter does not exist in @params, or * -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsGetString(virTypedParameterPtr params, @@ -433,6 +457,9 @@ virTypedParamsGetString(virTypedParameterPtr params, * if the parameter already exists in @params. * * Returns 0 on success, -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsAddInt(virTypedParameterPtr *params, @@ -479,6 +506,9 @@ virTypedParamsAddInt(virTypedParameterPtr *params, * error if the parameter already exists in @params. * * Returns 0 on success, -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsAddUInt(virTypedParameterPtr *params, @@ -525,6 +555,9 @@ virTypedParamsAddUInt(virTypedParameterPtr *params, * error if the parameter already exists in @params. * * Returns 0 on success, -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsAddLLong(virTypedParameterPtr *params, @@ -571,6 +604,9 @@ virTypedParamsAddLLong(virTypedParameterPtr *params, * error if the parameter already exists in @params. * * Returns 0 on success, -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsAddULLong(virTypedParameterPtr *params, @@ -617,6 +653,9 @@ virTypedParamsAddULLong(virTypedParameterPtr *params, * error if the parameter already exists in @params. * * Returns 0 on success, -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsAddDouble(virTypedParameterPtr *params, @@ -663,6 +702,9 @@ virTypedParamsAddDouble(virTypedParameterPtr *params, * error if the parameter already exists in @params. * * Returns 0 on success, -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsAddBoolean(virTypedParameterPtr *params, @@ -711,6 +753,9 @@ virTypedParamsAddBoolean(virTypedParameterPtr *params, * already exists in @params. * * Returns 0 on success, -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsAddString(virTypedParameterPtr *params, @@ -757,6 +802,9 @@ virTypedParamsAddString(virTypedParameterPtr *params, * key @name. * * Returns 0 on success, -1 on error. + * + * Since: v1.2.17 + * */ int virTypedParamsAddStringList(virTypedParameterPtr *params, @@ -802,6 +850,9 @@ virTypedParamsAddStringList(virTypedParameterPtr *params, * exists in @params. * * Returns 0 on success, -1 on error. + * + * Since: v1.0.2 + * */ int virTypedParamsAddFromString(virTypedParameterPtr *params, @@ -840,6 +891,9 @@ virTypedParamsAddFromString(virTypedParameterPtr *params, * is not freed; use virTypedParamsFree if you want it to be freed too. * * Returns nothing. + * + * Since: v1.0.2 + * */ void virTypedParamsClear(virTypedParameterPtr params, @@ -866,6 +920,9 @@ virTypedParamsClear(virTypedParameterPtr params, * @params. * * Returns nothing. + * + * Since: v1.0.2 + * */ void virTypedParamsFree(virTypedParameterPtr params, -- 2.35.1

This patch adds 'version' parameter to the generated XML API for enums. It'll require, for new additions, to add a comment with the version that the enum value was added. Note that the Since tag is removed from the comment as there is a proper field for it in the XML. Signed-off-by: Victor Toso <victortoso@redhat.com> --- scripts/apibuild.py | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index bdd3077c48..19e897b1ba 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -2178,6 +2178,26 @@ class docBuilder: self.scanModules() self.scanVersions() + # Fetch tags from the comment. Only 'Since' supported at the moment. + # Return the tags and the original comment without the tags. + def retrieve_comment_tags(self, name: str, comment: str + ) -> (str, str): + since = "" + if comment is not None: + comment_match = re.search(r"\(?Since: v?(\d+\.\d+\.\d+\.?\d?)\)?", + comment) + if comment_match: + # Remove Since tag from the comment + (start, end) = comment_match.span() + comment = comment[:start] + comment[end:] + comment = comment.strip() + # Only the version + since = comment_match.group(1) + + if since == "": + self.warning("Missing 'Since' tag for: " + name) + return (since, comment) + def modulename_file(self, file): module = os.path.basename(file) if module[-2:] == '.h': @@ -2211,7 +2231,15 @@ class docBuilder: if info[2] is not None and info[2] != '': output.write(" type='%s'" % info[2]) if info[1] is not None and info[1] != '': - output.write(" info='%s'" % escape(info[1])) + # Search for 'Since' version tag + (since, comment) = self.retrieve_comment_tags(name, info[1]) + if len(since) > 0: + output.write(" version='%s'" % escape(since)) + if len(comment) > 0: + output.write(" info='%s'" % escape(comment)) + else: + self.warning("Missing docstring for enum: " + name) + output.write("/>\n") def serialize_macro(self, output, name): -- 2.35.1

This patch adds 'version' parameter to the generated XML API for typedefs It'll require, for new additions, to add a comment with the version that the typedef value was added. An example bellow of code diff and the change in the generated XML. Note that the Since tag is removed from the comment as there is a proper field for it in the XML. Signed-off-by: Victor Toso <victortoso@redhat.com> --- scripts/apibuild.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index ddc2fff7af..24ca98bd1c 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -2298,9 +2298,11 @@ class docBuilder: def serialize_typedef(self, output, name): id = self.idx.typedefs[name] + (since, comment) = self.retrieve_comment_tags(name, id.extra) + version_tag = len(since) > 0 and f" version='{since}'" or "" if id.info[0:7] == 'struct ': - output.write(" <struct name='%s' file='%s' type='%s'" % ( - name, self.modulename_file(id.header), id.info)) + output.write(" <struct name='%s' file='%s' type='%s'%s" % ( + name, self.modulename_file(id.header), id.info, version_tag)) name = id.info[7:] if (name in self.idx.structs and isinstance(self.idx.structs[name].info, (list, tuple))): @@ -2323,12 +2325,11 @@ class docBuilder: else: output.write("/>\n") else: - output.write(" <typedef name='%s' file='%s' type='%s'" % ( - name, self.modulename_file(id.header), id.info)) + output.write(" <typedef name='%s' file='%s' type='%s'%s" % ( + name, self.modulename_file(id.header), id.info, version_tag)) try: - desc = id.extra - if desc is not None and desc != "": - output.write(">\n <info><![CDATA[%s]]></info>\n" % (desc)) + if comment is not None and comment != "": + output.write(">\n <info><![CDATA[%s]]></info>\n" % (comment)) output.write(" </typedef>\n") else: output.write("/>\n") -- 2.35.1

This patch adds 'version' parameter to generated XML API for functions and functypes. The 'version' metadata has been added with e0e0bf6628 by parsing .syms files. This commit does not override that but it will warn if there is not 'Since' metadata with new additions. There is not clear benefit for keeping both. For now, I've added a warning in case there is a mismatch between the version provided by .syms and docstring. Signed-off-by: Victor Toso <victortoso@redhat.com> --- scripts/apibuild.py | 126 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 113 insertions(+), 13 deletions(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index b77eea0624..ec10931151 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -111,6 +111,73 @@ ignored_functions = { "virErrorCopyNew": "private", } +# The version in the .sym file might differnt from +# the real version that the function was introduced. +# This dict's value is the correct version, as it should +# be in the docstrings. +ignored_function_versions = { + 'virDomainSetBlockThreshold': '3.2.0', + 'virGetLastErrorMessage': '1.0.5.2', + 'virNodeDeviceCreate': '0.5.0', + 'virAdmClientClose': '1.3.5', + 'virAdmClientFree': '1.3.5', + 'virAdmClientGetID': '1.3.5', + 'virAdmClientGetInfo': '1.3.5', + 'virAdmClientGetTimestamp': '1.3.5', + 'virAdmClientGetTransport': '1.3.5', + 'virAdmConnectClose': '1.2.17', + 'virAdmConnectGetLibVersion': '1.3.1', + 'virAdmConnectGetURI': '1.3.1', + 'virAdmConnectIsAlive': '1.3.1', + 'virAdmConnectListServers': '1.3.2', + 'virAdmConnectLookupServer': '1.3.3', + 'virAdmConnectOpen': '1.2.17', + 'virAdmConnectRef': '1.2.17', + 'virAdmConnectRegisterCloseCallback': '1.3.1', + 'virAdmConnectUnregisterCloseCallback': '1.3.1', + 'virAdmGetVersion': '1.3.0', + 'virAdmServerFree': '1.3.2', + 'virAdmServerGetClientLimits': '1.3.5', + 'virAdmServerGetName': '1.3.2', + 'virAdmServerGetThreadPoolParameters': '1.3.4', + 'virAdmServerListClients': '1.3.5', + 'virAdmServerLookupClient': '1.3.5', + 'virAdmServerSetClientLimits': '1.3.5', + 'virAdmServerSetThreadPoolParameters': '1.3.4', + 'virAdmServerUpdateTlsFiles': '6.2.0', + 'virConnectFindStoragePoolSources': '0.4.6', + 'virConnectNumOfDefinedDomains': '0.1.6', + 'virConnectOpenAuth': '0.4.1', + 'virDomainBlockPeek': '0.4.4', + 'virDomainMemoryPeek': '0.4.4', + 'virNetworkUpdate': '1.0.0', + 'virConnectClose': '0.0.1', + 'virConnectGetType': '0.0.1', + 'virConnectGetVersion': '0.0.1', + 'virConnectListDomains': '0.0.1', + 'virConnectNumOfDomains': '0.0.1', + 'virConnectOpen': '0.0.1', + 'virConnectOpenReadOnly': '0.0.1', + 'virDomainCreateLinux': '0.0.1', + 'virDomainDestroy': '0.0.1', + 'virDomainFree': '0.0.1', + 'virDomainGetID': '0.0.1', + 'virDomainGetInfo': '0.0.1', + 'virDomainGetMaxMemory': '0.0.1', + 'virDomainGetName': '0.0.1', + 'virDomainGetOSType': '0.0.1', + 'virDomainGetXMLDesc': '0.0.1', + 'virDomainLookupByID': '0.0.1', + 'virDomainLookupByName': '0.0.1', + 'virDomainRestore': '0.0.2', + 'virDomainResume': '0.0.1', + 'virDomainSave': '0.0.2', + 'virDomainSetMaxMemory': '0.0.1', + 'virDomainShutdown': '0.0.1', + 'virDomainSuspend': '0.0.1', + 'virGetVersion': '0.0.1', +} + ignored_macros = { "_virSchedParameter": "backward compatibility macro for virTypedParameter", "_virBlkioParameter": "backward compatibility macro for virTypedParameter", @@ -2185,9 +2252,10 @@ class docBuilder: self.scanVersions() # Fetch tags from the comment. Only 'Since' supported at the moment. - # Return the tags and the original comment without the tags. - def retrieve_comment_tags(self, name: str, comment: str - ) -> (str, str): + # For functions, since tags are on Return comments. + # Return the tags and the original comments, but without the tags. + def retrieve_comment_tags(self, name: str, comment: str, return_comment="" + ) -> (str, str, str): since = "" if comment is not None: comment_match = re.search(r"\(?Since: v?(\d+\.\d+\.\d+\.?\d?)\)?", @@ -2200,9 +2268,20 @@ class docBuilder: # Only the version since = comment_match.group(1) + if since == "" and return_comment is not None: + return_match = re.search(r"\(?Since: v?(\d+\.\d+\.\d+\.?\d?)\)?", + return_comment) + if return_match: + # Remove Since tag from the comment + (start, end) = return_match.span() + return_comment = return_comment[:start] + return_comment[end:] + return_comment = return_comment.strip() + # Only the version + since = return_match.group(1) + if since == "": self.warning("Missing 'Since' tag for: " + name) - return (since, comment) + return (since, comment, return_comment) def modulename_file(self, file): module = os.path.basename(file) @@ -2238,7 +2317,7 @@ class docBuilder: output.write(" type='%s'" % info[2]) if info[1] is not None and info[1] != '': # Search for 'Since' version tag - (since, comment) = self.retrieve_comment_tags(name, info[1]) + (since, comment, _) = self.retrieve_comment_tags(name, info[1]) if len(since) > 0: output.write(" version='%s'" % escape(since)) if len(comment) > 0: @@ -2268,7 +2347,7 @@ class docBuilder: else: output.write(" raw='%s'" % escape(rawValue)) - (since, comment) = self.retrieve_comment_tags(name, desc) + (since, comment, _) = self.retrieve_comment_tags(name, desc) if len(since) > 0: output.write(" version='%s'" % escape(since)) output.write(">\n") @@ -2302,7 +2381,7 @@ class docBuilder: def serialize_typedef(self, output, name): id = self.idx.typedefs[name] - (since, comment) = self.retrieve_comment_tags(name, id.extra) + (since, comment, _) = self.retrieve_comment_tags(name, id.extra) version_tag = len(since) > 0 and f" version='{since}'" or "" if id.info[0:7] == 'struct ': output.write(" <struct name='%s' file='%s' type='%s'%s" % ( @@ -2354,6 +2433,12 @@ class docBuilder: if name == debugsym and not quiet: print("=>", id) + (ret, params, desc) = id.info + return_comment = (ret is not None and ret[1] is not None) and ret[1] or "" + (since, comment, return_comment) = self.retrieve_comment_tags(name, desc, return_comment) + # Simple way to avoid setting empty version + version_tag = len(since) > 0 and f" version='{since}'" or "" + # NB: this is consumed by a regex in 'getAPIFilenames' in hvsupport.pl if id.type == "function": ver = self.versions[name] @@ -2363,9 +2448,10 @@ class docBuilder: name, self.modulename_file(id.header), self.modulename_file(id.module), self.versions[name])) else: - output.write(" <functype name='%s' file='%s' module='%s'>\n" % ( + output.write(" <functype name='%s' file='%s' module='%s'%s>\n" % ( name, self.modulename_file(id.header), - self.modulename_file(id.module))) + self.modulename_file(id.module), + version_tag)) # # Processing of conditionals modified by Bill 1/1/05 # @@ -2376,19 +2462,33 @@ class docBuilder: apstr = apstr + " && " apstr = apstr + cond output.write(" <cond>%s</cond>\n" % (apstr)) + try: - (ret, params, desc) = id.info - output.write(" <info><![CDATA[%s]]></info>\n" % (desc)) + # For functions, we get the since version from .syms files. + # This is an extra check to see that docstrings are correct + # and to avoid wrong versions in the .sym files too. + ver = name in self.versions and self.versions[name] or None + if len(since) > 0 and ver is not None and since != ver: + if name in ignored_function_versions: + allowedver = ignored_function_versions[name] + if allowedver != since: + self.warning(f"Function {name} has allowed version {allowedver} but docstring says {since}") + else: + self.warning(f"Function {name} has symversion {ver} but docstring says {since}") + + output.write(" <info><![CDATA[%s]]></info>\n" % (comment)) self.indexString(name, desc) + if ret[0] is not None: if ret[0] == "void": output.write(" <return type='void'/>\n") - elif (ret[1] is None or ret[1] == '') and name not in ignored_functions: + elif (return_comment == '') and name not in ignored_functions: self.error("Missing documentation for return of function `%s'" % name) else: output.write(" <return type='%s' info='%s'/>\n" % ( - ret[0], escape(ret[1]))) + ret[0], escape(return_comment))) self.indexString(name, ret[1]) + for param in params: if param[0] == 'void': continue -- 2.35.1

scripts/apibuild.py did not consider exporting external variable's comments into the XML API. This commits fixes that. Noe that the way that CParser is designed, it is currently possible to lose a parsed comment when parsing other fields as self.comment in several places. I've added a comment to highlight this. Signed-off-by: Victor Toso <victortoso@redhat.com> --- scripts/apibuild.py | 22 ++++++++++++++++------ 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/scripts/apibuild.py b/scripts/apibuild.py index 151eba37e6..9bdea648d4 100755 --- a/scripts/apibuild.py +++ b/scripts/apibuild.py @@ -1997,10 +1997,14 @@ class CParser: if token is None or token[0] != 'name': return token + variable_comment = None if token[1] == 'typedef': token = self.token() return self.parseTypedef(token) else: + # Store block of comment that might be from variable as + # the code uses self.comment a lot and it would lose it. + variable_comment = self.cleanup_code_comment(self.comment) token = self.parseType(token) type_orig = self.type if token is None or token[0] != "name": @@ -2046,8 +2050,10 @@ class CParser: not self.is_header, "struct", self.struct_fields) else: + # Just to use the cleanupComment function. + info = (type, variable_comment) self.index_add(self.name, self.filename, - not self.is_header, "variable", type) + not self.is_header, "variable", info) break elif token[1] == "(": token = self.token() @@ -2424,12 +2430,16 @@ class docBuilder: def serialize_variable(self, output, name): id = self.idx.variables[name] - if id.info is not None: - output.write(" <variable name='%s' file='%s' type='%s'/>\n" % ( - name, self.modulename_file(id.header), id.info)) + (type, comment) = id.info + (since, comment, _) = self.retrieve_comment_tags(name, comment) + version_tag = len(since) > 0 and f" version='{since}'" or "" + output.write(" <variable name='%s' file='%s' type='%s'%s" % ( + name, self.modulename_file(id.header), type, version_tag)) + if len(comment) == 0: + output.write("/>\n") else: - output.write(" <variable name='%s' file='%s'/>\n" % ( - name, self.modulename_file(id.header))) + output.write(">\n <info><![CDATA[%s]]></info>\n" % (comment)) + output.write(" </variable>\n") def serialize_function(self, output, name): id = self.idx.functions[name] -- 2.35.1