code.guido-berhoerster.org Contact

pws_init(3) Manual Page

Back to libpws

Name

pws_init, pws_finalize, pws_set_alloc_functions, pws_generate_uuid — initalize and deinitialize libpws

Synopsis

cc [ flag ...] file ... -lpws -lnettle [ library ...]

#include <pws.h>
int pws_init(void); 
 
void pws_finalize(void); 
 
void pws_set_alloc_functions(void *(*alloc_function)(size_t),
 void *(*realloc_function)(void *, size_t),
 void (*free_function)(void *, size_t),
 void *(*secure_alloc_function)(size_t),
 void *(*secure_realloc_function)(void *, size_t),
 void (*secure_free_function)(void *, size_t));
 
int pws_generate_uuid(unsigned char [static PWS3_UUID_SIZE]);
 
LIBPWS_VERSION_MAJOR

LIBPWS_VERSION_MINOR

LIBPWS_VERSION_MICRO

Description

The pws_init() function initializes libpws(3) and must be called before any other function from this library.

The pws_finalize() function deinitializes libpws(3) after which no other function from this library may be called.

The pws_set_alloc_functions() function specifies the functions which are used by libpws(3) to allocate, reallocate or free memory allowing for the use of custom allocators. pws_secure_alloc, pws_secure_realloc, and pws_secure_free are used to allocate, reallocate, and free memory containing potentially sensitive information such as passwords, this e.g. allows for wrapping the acutal allocation using operating system specific facilities to prevent memory from being paged to the swap area or to overwrite memory before deallocating it. Any argument set to NULL will result in the default function being used, these are malloc, realloc, and a wrapper around free. This function must be called after pws_init and before calling any other function from this library. It is not reentrant.

The pws_uuid_create() function generates a new random UUID following RFC4122 and places it in the array passed to it.

The macros LIBPWS_VERSION_MAJOR, LIBPWS_VERSION_MINOR, and LIBPWS_VERSION_MICRO can be used to check the major, minor, and micro version of the library.

Return Values

The pws_init() function returns 0 if the library was initialized successfully and -1 on failure.

The pws_generate_uuid() returns 0 if a new random UUID has been generated and -1 on failure.

See Also

libpws(3), pws3_file_create(3), RFC4122