(This probably seems like overanalysis of a simple problem. That's what I'm best at ;-) Due to oversight, the function virInterfaceLookupByMACString() can only return a single interface, but it's possible that a host may have more than one interface with the same MAC. Since the API had already been released by the time we realized this, the existing function will remain and a new one added that can return a list of interfaces. This new API will need to deal with the fact that the list length is effectively unbounded. I can see three ways of dealing with this, and want to learn which is preferred by others before spending time on the implementation. 1) The array containing the list is allocated by libvirt, freed by caller. int virInterfaceLookupAllByMACString(virConnectPtr conn, const char *mac, virInterfacePtr **matches); "matches" will point to an array of virInterfacePtr, and that array's length will be the return value. This array will be allocated by libvirt, but must be freed by the application when it's finished. Usage (ignoring errors, of course :-): virInterfacePtr *matches; int matchCt; matchCt = virInterfaceLookupAllByMACString(conn, "00:01:02:03:04:05", &matches); for (i = 0; i < matchCt; i++) { /* do something with an interface */ virInterfaceFree(matches[i]); } free(matches); 2) The array containing the list is allocated by the application, and its length sent to libvirt. Libvirt then returns the actual number of matches, which may be greater than the max length sent by the application, but only copies as many as the application asked for. If the application sends 0 as maxMatches and/or a NULL pointer instead of a pointer to an array, libvirt will return the actual length, but not the list itself. For example, if there are 3 interfaces matching, and maxMatches is set to 2, the function will still return 3, but only set two items in the matches array. int virInterfaceLookupAllByMACString(virConnectPtr conn, const char *mac, virInterfacePtr **matches, int maxMatches); This puts all the functionality needed in a single API function, but it will generally need to be called twice - once to learn the length, and the second (after allocating an array of appropriate size) to retrieve the list. virInterfacePtr *matches; int matchCtA, matchCtB; matchCtA = virInterfaceLookupAllByMACString(conn, "00:01:02:03:04:05", NULL, 0); matches = malloc (matchCt * sizeof(virInterfacePtr)); matchCtB = virInterfaceLookupAllByMACString(conn, "00:01:02:03:04:05", &matches, matchCt); for (i = 0; i < min(matchCtA, matchCtB); i++) { /* do something with an interface */ virInterfaceFree(matches[i]); } free(matches); 3) Again, the array containing the list is allocated by the application, but it learns the proper length to allocate by calling a different API function. The lookup function itself returns the number of interfaces delivered in the array, rather than the number of matches it *wanted* to put in the array. int virInterfaceCountAllByMACString(virConnectPtr conn, const char *mac); int virInterfaceLookupAllByMACString(virConnectPtr conn, const char *mac, virInterfacePtr **matches, int maxMatches); Usage: virInterfacePtr *matches; int matchCt; matchCt = virInterfaceCountAllByMACString(conn, "00:01:02:03:04:05"); matches = malloc (matchCt * sizeof(virInterfacePtr)); matchCt = virInterfaceLookupAllByMACString(conn, "00:01:02:03:04:05", &matches, matchCt); for (i = 0; i < matchCt; i++) { /* do something with an interface */ virInterfaceFree(matches[i]); } free(matches); ******* (3) is closest to behavior of other libvirt APIs, but requires more functions in the API, and could lead to situations where newly added interfaces aren't in the list (if a new interface is added between calling the Count function and the Lookup function) . (2) has a more compact API (one which matches the netcf API exactly), but has the same problems with potential bad counts. (1) seems like the cleanest API, but I don't know what others' opinions are on having libvirt allocate the array (since that's not how its done for other similar things, eg virConnectListInterface, virConnectListNetworks, etc), or maybe there's some limitation of the RPC I haven't considered that makes it unfeasible. Which should I implement?