.\" header.tmac.  GetData manual macros.
.\"
.\" Copyright (C) 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.

.\" Format a function name with optional trailer: func_name()trailer
.de FN \" func_name [trailer]
.nh
.BR \\$1 ()\\$2
.hy
..

.\" Format a reference to section 3 of the manual: name(3)trailer
.de F3 \" func_name [trailer]
.nh
.BR \\$1 (3)\\$2
.hy
..

.\" Format the header of a list of definitons
.de DD \" name alt...
.ie "\\$2"" \{ \
.TP 8
.PD
.B \\$1 \}
.el \{ \
.PP
.B \\$1
.PD 0
.DD \\$2 \\$3 \}
..

.\" Start a code block: Note: groff defines an undocumented .SC for
.\" Bell Labs man legacy reasons.
.de SC
.fam C
.na
.nh
..

.\" End a code block
.de EC
.hy
.ad
.fam
..

.\" Format a structure pointer member: struct->member\fRtrailer
.de SPM \" struct member trailer
.nh
.ie "\\$3"" .IB \\$1 ->\: \\$2
.el .IB \\$1 ->\: \\$2\fR\\$3
.hy
..

.\" Format a function argument
.de ARG \" name trailer
.nh
.ie "\\$2"" .I \\$1
.el .IR \\$1 \\$2
.hy
..

.\" Hyphenation exceptions
.hw sarray carray lincom linterp
.\" gd_alloc_funcs.3.  The gd_alloc_funcs man page.
.\"
.\" Copyright (C) 2016 D. V. Wiebe
.\"
.\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.\"
.\" This file is part of the GetData project.
.\"
.\" Permission is granted to copy, distribute and/or modify this document
.\" under the terms of the GNU Free Documentation License, Version 1.2 or
.\" any later version published by the Free Software Foundation; with no
.\" Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
.\" Texts.  A copy of the license is included in the `COPYING.DOC' file
.\" as part of this distribution.
.\"
.TH gd_alloc_funcs 3 "25 December 2016" "Version 0.10.0" "GETDATA"

.SH NAME
gd_alloc_funcs \(em specify an alternate memory manager for GetData's use

.SH SYNOPSIS
.SC
.B #include <getdata.h>
.HP
.BI "void gd_alloc_funcs(void *(*" malloc_func ")(size_t),
.BI "void (*" free_func )(void*));
.EC

.SH DESCRIPTION
The
.FN gd_alloc_funcs
allows the caller to specify an alternate memory manager for GetData to use
when providing dynamically allocated data to the caller.  The caller should
specify pointers to two functions which mimic the behaviour of the Standard
Library's
.F3 malloc
and
.F3 free
functions.  Passing NULL is equivalent to passing a pointer to the
corresponding Standard Library function, so the default memory manager can be
restored by passing all NULLs to this function.

The functions
.F3 gd_entry ,
.F3 gd_error_string ,
.F3 gd_fragment_affixes ,
.F3 gd_linterp_tablename ,
.F3 gd_raw_filename ,
and
.F3 gd_strtok
will use
.ARG malloc_func
to allocate the buffers they return.  The function
.F3 gd_free_entry_strings
will use the specified
.ARG free_func
to deallocate entry strings, and that same function will also be used by
GetData to deallocate strings returned by any registered parser callback
function (see
.F3 gd_cbopen ).

Internally, GetData may still allocate buffers on a different heap, and the
caller should not assume that any other pointer returned by the library were
allocated with the functions specified by this function.  Neither should the
caller assume that these functions won't be used by GetData library functions
to allocate and deallocate temporary buffers.

Changes made to the memory manager are global across GetData.  The caller should
only call this function when it is certain that no object allocated with the
old memory manager still exists.

This function always succeeds and returns no value.

.SH HISTORY
The
.FN gd_alloc_funcs
function appeared in GetData-0.10.0.

.SH SEE ALSO
.F3 free ,
.F3 gd_cbopen ,
.F3 gd_entry ,
.F3 gd_error_string ,
.F3 gd_fragment_affixes ,
.F3 gd_free_entry_strings
.F3 gd_linterp_tablename ,
.F3 gd_raw_filename ,
.F3 gd_strtok ,
.F3 malloc