4.2. Listing domains

The libvirt API exposes two lists of domains, the first contains running domains, while the second contains inactive, persistent domains. The lists are intended to be non-overlapping, exclusive sets, though there is always a small possibility that a domain can stop or start in between the querying of each set. The events API described later in this section provides a way to track all lifecycle changes avoiding this potential race condition.

The API for listing active domains, returns a list of domain IDs. Every running domain has a positive integer ID, uniquely identifying it amongst all running domains on the host. The API for listing active domains, virConnectListDomains, requires the caller to pass in a pre-allocated int array which will be filled in domain IDs. The return value will be -1 upon error, or the total number of array elements filled. To determine how large to make the ID array, the application can use the API call virConnectNumOfDomains. Putting these two calls together, a fragment of code which prints a list running domain IDs would be

        int i;
        int numDomains;
        int *activeDomains;

        numDomains = virConnectNumOfDomains(conn);

        activeDomains = malloc(sizeof(int) * numDomains);
        numDomains = virConnectListDomains(conn, activeDomains, numDomains);

        printf("Active domain IDs:\n");
        for (i = 0 ; i < numDomains ; i++) {
        printf("  %d\n", activeDomains[i]);
        }
        free(activeDomains);

Example 4.4. Listing active domains

In addition to the running domains, there may be some persistent inactive domain configurations stored on the host. Since an inactive domain does not have any ID identifier, the listing of inactive domains is exposed as a list of name strings. In a similar style to the API just discussed, the virConnectListDefinedDomains API requires the caller to provide a pre-allocated char * array which will be filled with domain name strings. The return value will be -1 upon error, or the total number of array elements filled with names. It is the caller's responsibility to free the memory associated with each returned name. As you might expect, there is also a virConnectNumOfDefinedDomains API to determine how many names are known. Putting these calls together, a fragment of code which prints a list of inactive persistent domain names would be:

        int i;
        int numDomains;
        char **inactiveDomains;

        numDomains = virConnectNumOfDefinedDomains(conn);

        inactiveDomains = malloc(sizeof(char *) * numDomains);
        numDomains = virConnectListDomains(conn, inactiveDomains, numDomains);

        printf("Inactive domain names:\n");
        for (i = 0 ; i < numDomains ; i++) {
        printf("  %s\n", inactiveDomains[i]);
        free(inactiveDomains[i]);
        }
        free(inactiveDomains);

Example 4.5. Listing inactive domains

The APIs for listing domains do not directly return the full virDomainPtr objects, since this may incur undue performance penalty for applications which wish to query the list of domains on a frequent basis. Given a domain ID or name, obtaining a full virDomainPtr object is a straightforward matter of calling one of the virDomainLookupBy{Name,ID} methods. So an example which obtained a virDomainPtr object for every domain, both active and inactive, would be:

        virDomainPtr *allDomains;
        int numDomains;
        int numActiveDomains, numInactiveDomains;
        char *inactiveDomains;
        int *activeDomains;

        numActiveDomains = virConnectNumOfDomains(conn);
        numInactiveDomains = virConnectNumOfDefinedDomains(conn);

        allDomains = malloc(sizeof(virDomainPtr) *
        numActiveDomains + numInactiveDomains);
        inactiveDomains = malloc(sizeof(char *) * numDomains);
        activeDomains = malloc(sizeof(int) * numDomains);

        numActiveDomains = virConnectListDomains(conn,
        activeDomains,
        numActiveDomains);
        numInactiveDomains = virConnectListDomains(conn,
        inactiveDomains,
        numInactiveDomains);

        for (i = 0 ; i < numActiveDomains ; i++) {
        allDomains[numDomains]
        = virDomainLookupByID(activeDomains[i]);
        numDomains++
        }

        for (i = 0 ; i < numInactiveDomains ; i++) {
        allDomains[numDomains]
        = virDomainLookupByName(inactiveDomains[i]);
        free(inactiveDomains[i]);
        numDomains++
        }
        free(activeDomains);
        free(inactiveDomains);