.TH "kdbhelper.h" 3elektra "Fri Aug 4 2023" "Version 0.11.0" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
kdbhelper.h \- Helper for memory management\&.  

.SH SYNOPSIS
.br
.PP
\fC#include <kdbmacros\&.h>\fP
.br
\fC#include <kdbtypes\&.h>\fP
.br
\fC#include <stdarg\&.h>\fP
.br
\fC#include <stddef\&.h>\fP
.br

.SS "Enumerations"

.in +1c
.ti -1c
.RI "enum \fBelektraLookupOptions\fP { \fBKDB_O_SPEC\fP = 1 << 15, \fBKDB_O_CREATE\fP = 1 << 16, \fBKDB_O_NOCASCADING\fP = 1 << 17, \fBKDB_O_NOSPEC\fP = 1 << 18, \fBKDB_O_NODEFAULT\fP = 1 << 19, \fBKDB_O_CALLBACK\fP = 1 << 20, \fBKDB_O_OPMPHM\fP = 1 << 21, \fBKDB_O_BINSEARCH\fP = 1 << 22 }"
.br
.RI "More lookup options\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "void * \fBelektraMalloc\fP (size_t size)"
.br
.RI "Allocate memory for Elektra\&. "
.ti -1c
.RI "void * \fBelektraCalloc\fP (size_t size)"
.br
.RI "Allocate memory for Elektra\&. "
.ti -1c
.RI "void \fBelektraFree\fP (void *ptr)"
.br
.RI "Free memory of Elektra or its backends\&. "
.ti -1c
.RI "int \fBelektraRealloc\fP (void **buffer, size_t size)"
.br
.RI "Reallocate Storage in a save way\&. "
.ti -1c
.RI "char * \fBelektraStrDup\fP (const char *s)"
.br
.RI "Copy string into new allocated memory\&. "
.ti -1c
.RI "void * \fBelektraMemDup\fP (const void *s, size_t l)"
.br
.RI "Copy buffer into new allocated memory\&. "
.ti -1c
.RI "char char * \fBelektraVFormat\fP (const char *format, va_list arg_list)"
.br
.RI "Does string formatting in fresh allocated memory\&. "
.ti -1c
.RI "int \fBelektraStrCmp\fP (const char *s1, const char *s2)"
.br
.RI "Compare Strings\&. "
.ti -1c
.RI "int \fBelektraStrNCmp\fP (const char *s1, const char *s2, size_t n)"
.br
.RI "Compare Strings up to a maximum length\&. "
.ti -1c
.RI "int \fBelektraStrCaseCmp\fP (const char *s1, const char *s2)"
.br
.RI "Compare Strings ignoring case\&. "
.ti -1c
.RI "int \fBelektraStrNCaseCmp\fP (const char *s1, const char *s2, size_t n)"
.br
.RI "Compare Strings ignoring case up to a maximum length\&. "
.ti -1c
.RI "int \fBelektraMemCaseCmp\fP (const char *s1, const char *s2, size_t size)"
.br
.RI "Compare two memory regions but make cmp chars uppercase before comparison\&. "
.ti -1c
.RI "size_t \fBelektraStrLen\fP (const char *s)"
.br
.RI "Calculates the length in bytes of a string\&. "
.in -1c
.SH "Detailed Description"
.PP 
Helper for memory management\&. 

Should be always preferred\&. Can be used for profiling and tracing\&.
.PP
\fBCopyright\fP
.RS 4
BSD License (see LICENSE\&.md or https://www.libelektra.org) 
.RE
.PP

.SH "Enumeration Type Documentation"
.PP 
.SS "enum \fBelektraLookupOptions\fP"

.PP
More lookup options\&. 
.PP
\fBEnumerator\fP
.in +1c
.TP
\fB\fIKDB_O_SPEC \fP\fP
Use the passed key as specification, instead of looking up the specification first\&. 
.TP
\fB\fIKDB_O_CREATE \fP\fP
Create the key if it was not found\&. 
.TP
\fB\fIKDB_O_NOCASCADING \fP\fP
Disable cascading search for keys starting with /\&. 
.TP
\fB\fIKDB_O_NOSPEC \fP\fP
Do not use specification for cascading keys (internal) 
.TP
\fB\fIKDB_O_NODEFAULT \fP\fP
Do not honor the default spec (internal) 
.TP
\fB\fIKDB_O_CALLBACK \fP\fP
For spec:/ lookups that traverse deeper into hierarchy (callback in \fBksLookup()\fP) 
.TP
\fB\fIKDB_O_OPMPHM \fP\fP
Overrule ksLookup search predictor to use OPMPHM, make sure to set ENABLE_OPTIMIZATIONS=ON at cmake\&. 
.TP
\fB\fIKDB_O_BINSEARCH \fP\fP
Overrule ksLookup search predictor to use Binary search for lookup\&. 
.SH "Function Documentation"
.PP 
.SS "void* elektraCalloc (size_t size)"

.PP
Allocate memory for Elektra\&. Memory will be set to 0\&.
.PP
\fBParameters\fP
.RS 4
\fIsize\fP the requested size 
.RE
.PP
\fBSee also\fP
.RS 4
\fBelektraMalloc\fP 
.RE
.PP

.SS "void elektraFree (void * ptr)"

.PP
Free memory of Elektra or its backends\&. 
.PP
\fBParameters\fP
.RS 4
\fIptr\fP the pointer to free
.RE
.PP
If ptr is NULL, no operation is performed\&.
.PP
\fBSee also\fP
.RS 4
\fBelektraMalloc\fP 
.RE
.PP

.SS "void* elektraMalloc (size_t size)"

.PP
Allocate memory for Elektra\&. 
.PP
.nf
if ((buffer = elektraMalloc (length)) == 0) {
        // here comes the failure handler
        // no allocation happened here, so don't use buffer
#if DEBUG
        fprintf (stderr, "Allocation error");
#endif
        // return with error
}

.fi
.PP
.PP
\fBParameters\fP
.RS 4
\fIsize\fP the requested size
.RE
.PP
This function is compatible to ANSI-C malloc 
.PP
\fBSee also\fP
.RS 4
\fBelektraFree\fP 
.PP
\fBelektraCalloc\fP 
.RE
.PP

.SS "int elektraMemCaseCmp (const char * s1, const char * s2, size_t size)"

.PP
Compare two memory regions but make cmp chars uppercase before comparison\&. 
.PP
\fBParameters\fP
.RS 4
\fIs1\fP The first string to be compared 
.br
\fIs2\fP The second string to be compared 
.br
\fIsize\fP to be compared
.RE
.PP
\fBReturns\fP
.RS 4
a negative number if s1 is less than s2 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI0\fP if s1 matches s2 
.RE
.PP
\fBReturns\fP
.RS 4
a positive number if s1 is greater than s2 
.RE
.PP

.SS "void* elektraMemDup (const void * s, size_t n)"

.PP
Copy buffer into new allocated memory\&. You need to free the memory yourself\&.
.PP
This function also works with \\0 characters in the buffer\&. The length is taken as given, it must be correct\&.
.PP
\fBReturns\fP
.RS 4
0 if out of memory, a pointer otherwise 
.RE
.PP
\fBParameters\fP
.RS 4
\fIs\fP must be an allocated buffer 
.br
\fIn\fP the number of bytes to copy from s 
.RE
.PP

.SS "int elektraRealloc (void ** buffer, size_t size)"

.PP
Reallocate Storage in a save way\&. 
.PP
.nf
if (elektraRealloc ((void **) & buffer, new_length) < 0) {
        // here comes the failure handler
        // you can still use the old buffer
#if DEBUG
        fprintf (stderr, "Reallocation error\n");
#endif
        elektraFree (buffer);
        buffer = 0;
        // return with error
}

.fi
.PP
.PP
\fBParameters\fP
.RS 4
\fIbuffer\fP is a pointer to a elektraMalloc 
.br
\fIsize\fP is the new size for the memory 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI-1\fP on failure 
.br
\fI0\fP on success 
.RE
.PP

.SS "int elektraStrCaseCmp (const char * s1, const char * s2)"

.PP
Compare Strings ignoring case\&. 
.PP
\fBParameters\fP
.RS 4
\fIs1\fP The first string to be compared 
.br
\fIs2\fP The second string to be compared
.RE
.PP
\fBReturns\fP
.RS 4
a negative number if s1 is less than s2 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI0\fP if s1 matches s2 
.RE
.PP
\fBReturns\fP
.RS 4
a positive number if s1 is greater than s2 
.RE
.PP

.SS "int elektraStrCmp (const char * s1, const char * s2)"

.PP
Compare Strings\&. 
.PP
\fBParameters\fP
.RS 4
\fIs1\fP The first string to be compared 
.br
\fIs2\fP The second string to be compared
.RE
.PP
\fBReturns\fP
.RS 4
a negative number if s1 is less than s2 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI0\fP if s1 matches s2 
.RE
.PP
\fBReturns\fP
.RS 4
a positive number if s1 is greater than s2 
.RE
.PP

.SS "char* elektraStrDup (const char * s)"

.PP
Copy string into new allocated memory\&. You need to free the memory yourself\&.
.PP
\fBNote\fP
.RS 4
that size is determined at runtime\&. So if you have a size information, don't use that function\&.
.RE
.PP
\fBParameters\fP
.RS 4
\fIs\fP the null-terminated string to duplicate
.RE
.PP
\fBReturns\fP
.RS 4
0 if out of memory, a pointer otherwise 
.RE
.PP
\fBPrecondition\fP
.RS 4
s must be a c-string\&. 
.RE
.PP
\fBSee also\fP
.RS 4
\fBelektraFree\fP 
.PP
\fBelektraStrLen\fP 
.PP
\fBelektraMemDup\fP 
.RE
.PP

.SS "size_t elektraStrLen (const char * s)"

.PP
Calculates the length in bytes of a string\&. This function differs from strlen() because it is Unicode and multibyte chars safe\&. While strlen() counts characters and ignores the final NULL, \fBelektraStrLen()\fP count bytes including the ending NULL\&.
.PP
It must not be used to search for / in the name, because it does not consider escaping\&. Instead use the unescaped name\&.
.PP
\fBSee also\fP
.RS 4
\fBkeyUnescapedName()\fP
.RE
.PP
\fBParameters\fP
.RS 4
\fIs\fP the string to get the length from 
.RE
.PP
\fBReturns\fP
.RS 4
number of bytes used by the string, including the final NULL\&. 
.RE
.PP

.SS "int elektraStrNCaseCmp (const char * s1, const char * s2, size_t n)"

.PP
Compare Strings ignoring case up to a maximum length\&. 
.PP
\fBParameters\fP
.RS 4
\fIs1\fP The first string to be compared 
.br
\fIs2\fP The second string to be compared 
.br
\fIn\fP The maximum length to be compared
.RE
.PP
\fBReturns\fP
.RS 4
a negative number if s1 is less than s2 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI0\fP if s1 matches s2 
.RE
.PP
\fBReturns\fP
.RS 4
a positive number if s1 is greater than s2 
.RE
.PP

.SS "int elektraStrNCmp (const char * s1, const char * s2, size_t n)"

.PP
Compare Strings up to a maximum length\&. 
.PP
\fBParameters\fP
.RS 4
\fIs1\fP The first string to be compared 
.br
\fIs2\fP The second string to be compared 
.br
\fIn\fP The maximum length to be compared
.RE
.PP
\fBReturns\fP
.RS 4
a negative number if s1 is less than s2 
.RE
.PP
\fBReturn values\fP
.RS 4
\fI0\fP if s1 matches s2 
.RE
.PP
\fBReturns\fP
.RS 4
a positive number if s1 is greater than s2 
.RE
.PP

.SS "char char* elektraVFormat (const char * format, va_list arg_list)"

.PP
Does string formatting in fresh allocated memory\&. 
.PP
\fBParameters\fP
.RS 4
\fIformat\fP as in vprintf() 
.br
\fIarg_list\fP as in vprintf()
.RE
.PP
\fBReturns\fP
.RS 4
new allocated memory (free with elektraFree) 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for Elektra from the source code\&.