C development

TODO: work in progress

Return values

Most of the API functions return 1 if successful or -1 on error.

The close function is an exception since it returns 0 if successful or -1 on error.

More details about the return values for each API function can be found in libqcow.h

Examples

The following examples require the following headers to be included:

#include <stdlib.h>
#include <stdio.h>

#include <libqcow.h>

file structure

Allocate file structure

libqcow_error_t *error = NULL;
libqcow_file_t *file = NULL;

if( libqcow_file_initialize(&file, &error) != 1 )
{
    fprintf(stderr, "Unable to initialize file.\n");

    libqcow_error_free(&error);

    exit(EXIT_FAILURE);
}

When calling the libqcow_file_initialize function the file argument must refer to NULL to allocate and initialize a file structure. The error argument is optional and can be NULL.

The function will return 1 if successful or -1 on error. On error an the library creates an error structure except if error is NULL e.g.

libqcow_file_initialize(&file, NULL);

The error structure must be freed by calling the libqcow_error_free function.

Free file structure

if( libqcow_file_free(&file, &error) != 1 )
{
    fprintf(stderr, "Unable to free file.\n");

    libqcow_error_free(&error);

    exit(EXIT_FAILURE);
}

The function will return 1 if successful or -1 on error. File is set to NULL. The function will also close the file if it was opened.

Open file

filename = "image.qcow2";

if( libqcow_file_open(file, filename, LIBQCOW_OPEN_READ, &error) != 1 )
{
    fprintf(stderr, "Unable to open file.\n" );

    libqcow_file_free(&file, NULL);
    libqcow_error_free(&error);

    exit(EXIT_FAILURE);
}

libqcow provides both narrow and wide character string functions for filenames. The wide character equivalent of the open function is libqcow_file_open_wide. By default libqcow will only enable wide character string support on Windows since other operating systems have build-in support for UTF-8 narrow character strings.

To compile with wide character support add --enable-wide-character-type=yes to configure, e.g.:

./configure --enable-wide-character-type=yes

Or on Windows define WINAPI and either _UNICODE or UNICODE

When wide character string support is enabled LIBQCOW_HAVE_WIDE_CHARACTER_TYPE is defined in <libqcow/features.h>

Open file using a file-like object

TODO describe

libqcow allows to be compiled with file-like object support using libbfio. The libqcow configure script will automatically detect if a compatible version of libbfio is available.

When libbfio is support is enabled LIBQCOW_HAVE_BFIO is defined in <libqcow/features.h>

Close file

if( libqcow_file_close(file, &error) != 0 )
{
    fprintf(stderr, "Unable to close file.\n" );

    libqcow_file_free(&file, NULL);
    libqcow_error_free(&error);

    exit(EXIT_FAILURE);
}

Also see

• libqcow.h
• man 3 libqcow