C development

C/C++ development

The following examples require the following headers to be included:

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

#include <libbfio.h>

Most of the 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 can be found in libbfio.h

Allocate handle structure

libbfio_error_t *error   = NULL;
libbfio_handle_t *handle = NULL;

/* libbfio_file_initialize is a convenience function to create a file-based BFIO handle
 */
if( libbfio_file_initialize(&handle, &error) != 1 )
{
    fprintf(stderr, "Unable to initialize file handle.\n");

    libbfio_error_free(&error);

    exit(EXIT_FAILURE);
}

When calling the libbfio_handle_initialize function the handle argument must refer to NULL to allocate and initialize a handle 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.

libbfio_file_initialize(&handle, NULL)

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

Free handle structure

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

    libbfio_error_free(&error);

    exit(EXIT_FAILURE);
}

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

Open handle

filename = "my_file.txt";

filename_length = strlen(filename);

/* libbfio_file_set_name is a convenience function to set the name of a file-based BFIO handle
 */
if( libbfio_file_set_name(handle, filename, filename_length, &error ) != 1 )
{
    fprintf(stderr, "Unable to set file name.\n" );

    libbfio_handle_free(&handle, NULL);
    libbfio_error_free(&error);

    exit(EXIT_FAILURE);
}

if( libbfio_handle_open(handle, LIBBFIO_OPEN_READ, &error) != 1 )
{
    fprintf(stderr, "Unable to open handle.\n" );

    libbfio_handle_free(&handle, NULL);
    libbfio_error_free(&error);

    exit(EXIT_FAILURE);
}

Libbfio provides both narrow and wide character string functions for filenames. The wide character equivalent of the open function is libbfio_file_set_name_wide. By default libbfio 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 LIBBFIO_HAVE_WIDE_CHARACTER_TYPE is defined in <libbfio/features.h>

Close handle

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

    libbfio_handle_free(&handle, NULL);
    libbfio_error_free(&error);

    exit(EXIT_FAILURE);
}

Also see

• libbfio.h
• man 3 libbfio