mirror of
https://github.com/samba-team/samba.git
synced 2024-12-23 17:34:34 +03:00
Share talloc source code between Samba 3 and Samba 4.
This commit is contained in:
parent
ec1c854f21
commit
80a5da73e9
@ -23,7 +23,7 @@ m4_include(m4/check_path.m4)
|
||||
|
||||
AC_LIBREPLACE_CC_CHECKS
|
||||
|
||||
m4_include(lib/talloc/libtalloc.m4)
|
||||
m4_include(../talloc/libtalloc.m4)
|
||||
|
||||
LIBTALLOC_OBJ0=""
|
||||
for obj in ${TALLOC_OBJ}; do
|
||||
|
@ -652,7 +652,7 @@ typedef char fstring[FSTRING_LEN];
|
||||
#include "tdb.h"
|
||||
#include "util_tdb.h"
|
||||
|
||||
#include "lib/talloc/talloc.h"
|
||||
#include "../talloc/talloc.h"
|
||||
/* And a little extension. Abort on type mismatch */
|
||||
#define talloc_get_type_abort(ptr, type) \
|
||||
(type *)talloc_check_name_abort(ptr, #type)
|
||||
|
@ -35,7 +35,7 @@
|
||||
#ifndef _TALLOC_STACK_H
|
||||
#define _TALLOC_STACK_H
|
||||
|
||||
#include "lib/talloc/talloc.h"
|
||||
#include "../talloc/talloc.h"
|
||||
|
||||
/*
|
||||
* Create a new talloc stack frame.
|
||||
|
@ -115,6 +115,7 @@ smbreadlinesrcdir := $(samba4srcdir)/lib/smbreadline
|
||||
ntp_signdsrcdir := $(samba4srcdir)/ntp_signd
|
||||
tdbsrcdir := $(samba4srcdir)/lib/tdb
|
||||
ldbsrcdir := $(samba4srcdir)/lib/ldb
|
||||
tallocsrcdir := $(samba4srcdir)/lib/talloc
|
||||
override ASN1C = bin/asn1_compile4
|
||||
override ET_COMPILER = bin/compile_et4
|
||||
include samba4-data.mk
|
||||
|
@ -103,6 +103,7 @@ pyscriptsrcdir := $(srcdir)/scripting/python
|
||||
kdcsrcdir := kdc
|
||||
ntp_signdsrcdir := ntp_signd
|
||||
wmisrcdir := lib/wmi
|
||||
tallocsrcdir := ../talloc
|
||||
|
||||
include data.mk
|
||||
|
||||
|
@ -41,8 +41,8 @@ AC_CONFIG_FILES(librpc/dcerpc_atsvc.pc)
|
||||
SMB_EXT_LIB_FROM_PKGCONFIG(LIBTALLOC, talloc >= 1.2.0,
|
||||
[],
|
||||
[
|
||||
m4_include(lib/talloc/libtalloc.m4)
|
||||
SMB_INCLUDE_MK(lib/talloc/config.mk)
|
||||
m4_include(../talloc/libtalloc.m4)
|
||||
SMB_INCLUDE_MK(../talloc/config.mk)
|
||||
]
|
||||
)
|
||||
|
||||
@ -159,7 +159,7 @@ then
|
||||
builddir_headers="-I\$(builddir)/include -I\$(builddir) -I\$(builddir)/lib ";
|
||||
fi
|
||||
|
||||
CPPFLAGS="$builddir_headers-I\$(srcdir)/include -I\$(srcdir) -I\$(srcdir)/lib -I\$(srcdir)/lib/replace -I\$(srcdir)/lib/talloc -D_SAMBA_BUILD_=4 -DHAVE_CONFIG_H $CPPFLAGS"
|
||||
CPPFLAGS="$builddir_headers-I\$(srcdir)/include -I\$(srcdir) -I\$(srcdir)/lib -I\$(srcdir)/lib/replace -I\$(srcdir)/../talloc -D_SAMBA_BUILD_=4 -DHAVE_CONFIG_H $CPPFLAGS"
|
||||
|
||||
SMB_WRITE_PERLVARS(build/smb_build/config.pm)
|
||||
|
||||
|
@ -1,43 +0,0 @@
|
||||
#!gmake
|
||||
#
|
||||
prefix = @prefix@
|
||||
datarootdir = @datarootdir@
|
||||
exec_prefix = @exec_prefix@
|
||||
includedir = @includedir@
|
||||
libdir = @libdir@
|
||||
mandir = @mandir@
|
||||
VPATH = @srcdir@:@libreplacedir@
|
||||
srcdir = @srcdir@
|
||||
builddir = @builddir@
|
||||
XSLTPROC = @XSLTPROC@
|
||||
INSTALLCMD = @INSTALL@
|
||||
CC = @CC@
|
||||
CFLAGS = @CFLAGS@ -DHAVE_CONFIG_H= -I. -I@srcdir@
|
||||
EXTRA_TARGETS = @DOC_TARGET@
|
||||
PICFLAG = @PICFLAG@
|
||||
PACKAGE_VERSION = @PACKAGE_VERSION@
|
||||
SHLIBEXT = @SHLIBEXT@
|
||||
SHLD = @SHLD@
|
||||
SHLD_FLAGS = @SHLD_FLAGS@
|
||||
tallocdir = @tallocdir@
|
||||
|
||||
LIBOBJ = $(TALLOC_OBJ) @LIBREPLACEOBJ@
|
||||
|
||||
all:: showflags $(EXTRA_TARGETS)
|
||||
|
||||
include $(tallocdir)/rules.mk
|
||||
include $(tallocdir)/talloc.mk
|
||||
|
||||
$(TALLOC_SOLIB): $(LIBOBJ)
|
||||
$(SHLD) $(SHLD_FLAGS) -o $@ $(LIBOBJ) @SONAMEFLAG@$(TALLOC_SONAME)
|
||||
|
||||
check: test
|
||||
|
||||
installcheck:: test install
|
||||
|
||||
distclean:: clean
|
||||
rm -f Makefile
|
||||
rm -f config.log config.status config.h config.cache
|
||||
|
||||
realdistclean:: distclean
|
||||
rm -f configure config.h.in
|
@ -1,13 +0,0 @@
|
||||
1.0.1 26 May 2007
|
||||
|
||||
BUGS
|
||||
|
||||
* Set name of correctly when using talloc_append_string() (metze)
|
||||
|
||||
LICENSE
|
||||
|
||||
* Change license of files in lib/replace to LGPL (was GPL). (jelmer)
|
||||
|
||||
1.0.0 30 April 2007
|
||||
|
||||
Initial release.
|
1
source4/lib/talloc/aclocal.m4
vendored
1
source4/lib/talloc/aclocal.m4
vendored
@ -1 +0,0 @@
|
||||
m4_include(libreplace.m4)
|
@ -1,14 +0,0 @@
|
||||
#!/bin/sh
|
||||
|
||||
rm -rf autom4te.cache
|
||||
rm -f configure config.h.in
|
||||
|
||||
IPATHS="-I libreplace -I lib/replace -I ../libreplace -I ../replace"
|
||||
autoconf $IPATHS || exit 1
|
||||
autoheader $IPATHS || exit 1
|
||||
|
||||
rm -rf autom4te.cache
|
||||
|
||||
echo "Now run ./configure and then make."
|
||||
exit 0
|
||||
|
1464
source4/lib/talloc/config.guess
vendored
1464
source4/lib/talloc/config.guess
vendored
File diff suppressed because it is too large
Load Diff
@ -1,7 +0,0 @@
|
||||
[LIBRARY::LIBTALLOC]
|
||||
OUTPUT_TYPE = MERGED_OBJ
|
||||
CFLAGS = -Ilib/talloc
|
||||
|
||||
LIBTALLOC_OBJ_FILES = lib/talloc/talloc.o
|
||||
|
||||
MANPAGES += $(tallocdir)/talloc.3
|
1577
source4/lib/talloc/config.sub
vendored
1577
source4/lib/talloc/config.sub
vendored
File diff suppressed because it is too large
Load Diff
@ -1,24 +0,0 @@
|
||||
AC_PREREQ(2.50)
|
||||
AC_INIT(talloc, 1.2.0)
|
||||
AC_CONFIG_SRCDIR([talloc.c])
|
||||
AC_SUBST(datarootdir)
|
||||
AC_CONFIG_HEADER(config.h)
|
||||
|
||||
AC_LIBREPLACE_ALL_CHECKS
|
||||
|
||||
m4_include(libtalloc.m4)
|
||||
|
||||
AC_PATH_PROG(XSLTPROC,xsltproc)
|
||||
DOC_TARGET=""
|
||||
if test -n "$XSLTPROC"; then
|
||||
DOC_TARGET=doc
|
||||
fi
|
||||
AC_SUBST(DOC_TARGET)
|
||||
|
||||
AC_LD_PICFLAG
|
||||
AC_LD_SHLIBEXT
|
||||
AC_LD_SONAMEFLAG
|
||||
AC_LIBREPLACE_SHLD
|
||||
AC_LIBREPLACE_SHLD_FLAGS
|
||||
|
||||
AC_OUTPUT(Makefile talloc.pc)
|
@ -1,238 +0,0 @@
|
||||
#! /bin/sh
|
||||
#
|
||||
# install - install a program, script, or datafile
|
||||
# This comes from X11R5.
|
||||
#
|
||||
# Calling this script install-sh is preferred over install.sh, to prevent
|
||||
# `make' implicit rules from creating a file called install from it
|
||||
# when there is no Makefile.
|
||||
#
|
||||
# This script is compatible with the BSD install script, but was written
|
||||
# from scratch.
|
||||
#
|
||||
|
||||
|
||||
# set DOITPROG to echo to test this script
|
||||
|
||||
# Don't use :- since 4.3BSD and earlier shells don't like it.
|
||||
doit="${DOITPROG-}"
|
||||
|
||||
|
||||
# put in absolute paths if you don't have them in your path; or use env. vars.
|
||||
|
||||
mvprog="${MVPROG-mv}"
|
||||
cpprog="${CPPROG-cp}"
|
||||
chmodprog="${CHMODPROG-chmod}"
|
||||
chownprog="${CHOWNPROG-chown}"
|
||||
chgrpprog="${CHGRPPROG-chgrp}"
|
||||
stripprog="${STRIPPROG-strip}"
|
||||
rmprog="${RMPROG-rm}"
|
||||
mkdirprog="${MKDIRPROG-mkdir}"
|
||||
|
||||
transformbasename=""
|
||||
transform_arg=""
|
||||
instcmd="$mvprog"
|
||||
chmodcmd="$chmodprog 0755"
|
||||
chowncmd=""
|
||||
chgrpcmd=""
|
||||
stripcmd=""
|
||||
rmcmd="$rmprog -f"
|
||||
mvcmd="$mvprog"
|
||||
src=""
|
||||
dst=""
|
||||
dir_arg=""
|
||||
|
||||
while [ x"$1" != x ]; do
|
||||
case $1 in
|
||||
-c) instcmd="$cpprog"
|
||||
shift
|
||||
continue;;
|
||||
|
||||
-d) dir_arg=true
|
||||
shift
|
||||
continue;;
|
||||
|
||||
-m) chmodcmd="$chmodprog $2"
|
||||
shift
|
||||
shift
|
||||
continue;;
|
||||
|
||||
-o) chowncmd="$chownprog $2"
|
||||
shift
|
||||
shift
|
||||
continue;;
|
||||
|
||||
-g) chgrpcmd="$chgrpprog $2"
|
||||
shift
|
||||
shift
|
||||
continue;;
|
||||
|
||||
-s) stripcmd="$stripprog"
|
||||
shift
|
||||
continue;;
|
||||
|
||||
-t=*) transformarg=`echo $1 | sed 's/-t=//'`
|
||||
shift
|
||||
continue;;
|
||||
|
||||
-b=*) transformbasename=`echo $1 | sed 's/-b=//'`
|
||||
shift
|
||||
continue;;
|
||||
|
||||
*) if [ x"$src" = x ]
|
||||
then
|
||||
src=$1
|
||||
else
|
||||
# this colon is to work around a 386BSD /bin/sh bug
|
||||
:
|
||||
dst=$1
|
||||
fi
|
||||
shift
|
||||
continue;;
|
||||
esac
|
||||
done
|
||||
|
||||
if [ x"$src" = x ]
|
||||
then
|
||||
echo "install: no input file specified"
|
||||
exit 1
|
||||
else
|
||||
true
|
||||
fi
|
||||
|
||||
if [ x"$dir_arg" != x ]; then
|
||||
dst=$src
|
||||
src=""
|
||||
|
||||
if [ -d $dst ]; then
|
||||
instcmd=:
|
||||
else
|
||||
instcmd=mkdir
|
||||
fi
|
||||
else
|
||||
|
||||
# Waiting for this to be detected by the "$instcmd $src $dsttmp" command
|
||||
# might cause directories to be created, which would be especially bad
|
||||
# if $src (and thus $dsttmp) contains '*'.
|
||||
|
||||
if [ -f $src -o -d $src ]
|
||||
then
|
||||
true
|
||||
else
|
||||
echo "install: $src does not exist"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [ x"$dst" = x ]
|
||||
then
|
||||
echo "install: no destination specified"
|
||||
exit 1
|
||||
else
|
||||
true
|
||||
fi
|
||||
|
||||
# If destination is a directory, append the input filename; if your system
|
||||
# does not like double slashes in filenames, you may need to add some logic
|
||||
|
||||
if [ -d $dst ]
|
||||
then
|
||||
dst="$dst"/`basename $src`
|
||||
else
|
||||
true
|
||||
fi
|
||||
fi
|
||||
|
||||
## this sed command emulates the dirname command
|
||||
dstdir=`echo $dst | sed -e 's,[^/]*$,,;s,/$,,;s,^$,.,'`
|
||||
|
||||
# Make sure that the destination directory exists.
|
||||
# this part is taken from Noah Friedman's mkinstalldirs script
|
||||
|
||||
# Skip lots of stat calls in the usual case.
|
||||
if [ ! -d "$dstdir" ]; then
|
||||
defaultIFS='
|
||||
'
|
||||
IFS="${IFS-${defaultIFS}}"
|
||||
|
||||
oIFS="${IFS}"
|
||||
# Some sh's can't handle IFS=/ for some reason.
|
||||
IFS='%'
|
||||
set - `echo ${dstdir} | sed -e 's@/@%@g' -e 's@^%@/@'`
|
||||
IFS="${oIFS}"
|
||||
|
||||
pathcomp=''
|
||||
|
||||
while [ $# -ne 0 ] ; do
|
||||
pathcomp="${pathcomp}${1}"
|
||||
shift
|
||||
|
||||
if [ ! -d "${pathcomp}" ] ;
|
||||
then
|
||||
$mkdirprog "${pathcomp}"
|
||||
else
|
||||
true
|
||||
fi
|
||||
|
||||
pathcomp="${pathcomp}/"
|
||||
done
|
||||
fi
|
||||
|
||||
if [ x"$dir_arg" != x ]
|
||||
then
|
||||
$doit $instcmd $dst &&
|
||||
|
||||
if [ x"$chowncmd" != x ]; then $doit $chowncmd $dst; else true ; fi &&
|
||||
if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dst; else true ; fi &&
|
||||
if [ x"$stripcmd" != x ]; then $doit $stripcmd $dst; else true ; fi &&
|
||||
if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dst; else true ; fi
|
||||
else
|
||||
|
||||
# If we're going to rename the final executable, determine the name now.
|
||||
|
||||
if [ x"$transformarg" = x ]
|
||||
then
|
||||
dstfile=`basename $dst`
|
||||
else
|
||||
dstfile=`basename $dst $transformbasename |
|
||||
sed $transformarg`$transformbasename
|
||||
fi
|
||||
|
||||
# don't allow the sed command to completely eliminate the filename
|
||||
|
||||
if [ x"$dstfile" = x ]
|
||||
then
|
||||
dstfile=`basename $dst`
|
||||
else
|
||||
true
|
||||
fi
|
||||
|
||||
# Make a temp file name in the proper directory.
|
||||
|
||||
dsttmp=$dstdir/#inst.$$#
|
||||
|
||||
# Move or copy the file name to the temp name
|
||||
|
||||
$doit $instcmd $src $dsttmp &&
|
||||
|
||||
trap "rm -f ${dsttmp}" 0 &&
|
||||
|
||||
# and set any options; do chmod last to preserve setuid bits
|
||||
|
||||
# If any of these fail, we abort the whole thing. If we want to
|
||||
# ignore errors from any of these, just make sure not to ignore
|
||||
# errors from the above "$doit $instcmd $src $dsttmp" command.
|
||||
|
||||
if [ x"$chowncmd" != x ]; then $doit $chowncmd $dsttmp; else true;fi &&
|
||||
if [ x"$chgrpcmd" != x ]; then $doit $chgrpcmd $dsttmp; else true;fi &&
|
||||
if [ x"$stripcmd" != x ]; then $doit $stripcmd $dsttmp; else true;fi &&
|
||||
if [ x"$chmodcmd" != x ]; then $doit $chmodcmd $dsttmp; else true;fi &&
|
||||
|
||||
# Now rename the file to the real destination.
|
||||
|
||||
$doit $rmcmd -f $dstdir/$dstfile &&
|
||||
$doit $mvcmd $dsttmp $dstdir/$dstfile
|
||||
|
||||
fi &&
|
||||
|
||||
|
||||
exit 0
|
@ -1,33 +0,0 @@
|
||||
dnl find the talloc sources. This is meant to work both for
|
||||
dnl talloc standalone builds, and builds of packages using talloc
|
||||
tallocdir=""
|
||||
tallocpaths=". lib/talloc talloc ../talloc"
|
||||
for d in $tallocpaths; do
|
||||
if test -f "$srcdir/$d/talloc.c"; then
|
||||
tallocdir="$d"
|
||||
AC_SUBST(tallocdir)
|
||||
break;
|
||||
fi
|
||||
done
|
||||
if test x"$tallocdir" = "x"; then
|
||||
AC_MSG_ERROR([cannot find talloc source in $tallocpaths])
|
||||
fi
|
||||
TALLOC_OBJ="talloc.o"
|
||||
AC_SUBST(TALLOC_OBJ)
|
||||
|
||||
TALLOC_CFLAGS="-I$srcdir/$tallocdir"
|
||||
AC_SUBST(TALLOC_CFLAGS)
|
||||
|
||||
TALLOC_LIBS=""
|
||||
AC_SUBST(TALLOC_LIBS)
|
||||
|
||||
AC_CHECK_SIZEOF(size_t,cross)
|
||||
AC_CHECK_SIZEOF(void *,cross)
|
||||
|
||||
if test $ac_cv_sizeof_size_t -lt $ac_cv_sizeof_void_p; then
|
||||
AC_WARN([size_t cannot represent the amount of used memory of a process])
|
||||
AC_WARN([please report this to <samba-technical@samba.org>])
|
||||
AC_WARN([sizeof(size_t) = $ac_cv_sizeof_size_t])
|
||||
AC_WARN([sizeof(void *) = $ac_cv_sizeof_void_p])
|
||||
AC_ERROR([sizeof(size_t) < sizeof(void *)])
|
||||
fi
|
@ -1,18 +0,0 @@
|
||||
.SUFFIXES: .c .o .3 .3.xml .xml .html
|
||||
|
||||
showflags::
|
||||
@echo 'talloc will be compiled with flags:'
|
||||
@echo ' CFLAGS = $(CFLAGS)'
|
||||
@echo ' LIBS = $(LIBS)'
|
||||
|
||||
.c.o:
|
||||
$(CC) $(PICFLAG) -o $@ -c $< $(CFLAGS)
|
||||
|
||||
.3.xml.3:
|
||||
-test -z "$(XSLTPROC)" || $(XSLTPROC) --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
|
||||
|
||||
.xml.html:
|
||||
-test -z "$(XSLTPROC)" || $(XSLTPROC) --nonet -o $@ http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl $<
|
||||
|
||||
distclean::
|
||||
rm -f *~ */*~
|
@ -1,738 +0,0 @@
|
||||
<?xml version="1.0"?>
|
||||
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
|
||||
<refentry>
|
||||
<refmeta>
|
||||
<refentrytitle>talloc</refentrytitle>
|
||||
<manvolnum>3</manvolnum>
|
||||
</refmeta>
|
||||
<refnamediv>
|
||||
<refname>talloc</refname>
|
||||
<refpurpose>hierarchical reference counted memory pool system with destructors</refpurpose>
|
||||
</refnamediv>
|
||||
<refsynopsisdiv>
|
||||
<synopsis>#include <talloc/talloc.h></synopsis>
|
||||
</refsynopsisdiv>
|
||||
<refsect1><title>DESCRIPTION</title>
|
||||
<para>
|
||||
If you are used to talloc from Samba3 then please read this
|
||||
carefully, as talloc has changed a lot.
|
||||
</para>
|
||||
<para>
|
||||
The new talloc is a hierarchical, reference counted memory pool
|
||||
system with destructors. Quite a mouthful really, but not too bad
|
||||
once you get used to it.
|
||||
</para>
|
||||
<para>
|
||||
Perhaps the biggest change from Samba3 is that there is no
|
||||
distinction between a "talloc context" and a "talloc pointer". Any
|
||||
pointer returned from talloc() is itself a valid talloc context.
|
||||
This means you can do this:
|
||||
</para>
|
||||
<programlisting>
|
||||
struct foo *X = talloc(mem_ctx, struct foo);
|
||||
X->name = talloc_strdup(X, "foo");
|
||||
</programlisting>
|
||||
<para>
|
||||
and the pointer <literal role="code">X->name</literal>
|
||||
would be a "child" of the talloc context <literal
|
||||
role="code">X</literal> which is itself a child of
|
||||
<literal role="code">mem_ctx</literal>. So if you do
|
||||
<literal role="code">talloc_free(mem_ctx)</literal> then
|
||||
it is all destroyed, whereas if you do <literal
|
||||
role="code">talloc_free(X)</literal> then just <literal
|
||||
role="code">X</literal> and <literal
|
||||
role="code">X->name</literal> are destroyed, and if
|
||||
you do <literal
|
||||
role="code">talloc_free(X->name)</literal> then just
|
||||
the name element of <literal role="code">X</literal> is
|
||||
destroyed.
|
||||
</para>
|
||||
<para>
|
||||
If you think about this, then what this effectively gives you is an
|
||||
n-ary tree, where you can free any part of the tree with
|
||||
talloc_free().
|
||||
</para>
|
||||
<para>
|
||||
If you find this confusing, then I suggest you run the <literal
|
||||
role="code">testsuite</literal> program to watch talloc
|
||||
in action. You may also like to add your own tests to <literal
|
||||
role="code">testsuite.c</literal> to clarify how some
|
||||
particular situation is handled.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1><title>TALLOC API</title>
|
||||
<para>
|
||||
The following is a complete guide to the talloc API. Read it all at
|
||||
least twice.
|
||||
</para>
|
||||
<refsect2><title>(type *)talloc(const void *ctx, type);</title>
|
||||
<para>
|
||||
The talloc() macro is the core of the talloc library. It takes a
|
||||
memory <emphasis role="italic">ctx</emphasis> and a <emphasis
|
||||
role="italic">type</emphasis>, and returns a pointer to a new
|
||||
area of memory of the given <emphasis
|
||||
role="italic">type</emphasis>.
|
||||
</para>
|
||||
<para>
|
||||
The returned pointer is itself a talloc context, so you can use
|
||||
it as the <emphasis role="italic">ctx</emphasis> argument to more
|
||||
calls to talloc() if you wish.
|
||||
</para>
|
||||
<para>
|
||||
The returned pointer is a "child" of the supplied context. This
|
||||
means that if you talloc_free() the <emphasis
|
||||
role="italic">ctx</emphasis> then the new child disappears as
|
||||
well. Alternatively you can free just the child.
|
||||
</para>
|
||||
<para>
|
||||
The <emphasis role="italic">ctx</emphasis> argument to talloc()
|
||||
can be NULL, in which case a new top level context is created.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_size(const void *ctx, size_t size);</title>
|
||||
<para>
|
||||
The function talloc_size() should be used when you don't have a
|
||||
convenient type to pass to talloc(). Unlike talloc(), it is not
|
||||
type safe (as it returns a void *), so you are on your own for
|
||||
type checking.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>(typeof(ptr)) talloc_ptrtype(const void *ctx, ptr);</title>
|
||||
<para>
|
||||
The talloc_ptrtype() macro should be used when you have a pointer and
|
||||
want to allocate memory to point at with this pointer. When compiling
|
||||
with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
|
||||
and talloc_get_name() will return the current location in the source file.
|
||||
and not the type.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>int talloc_free(void *ptr);</title>
|
||||
<para>
|
||||
The talloc_free() function frees a piece of talloc memory, and
|
||||
all its children. You can call talloc_free() on any pointer
|
||||
returned by talloc().
|
||||
</para>
|
||||
<para>
|
||||
The return value of talloc_free() indicates success or failure,
|
||||
with 0 returned for success and -1 for failure. The only
|
||||
possible failure condition is if <emphasis
|
||||
role="italic">ptr</emphasis> had a destructor attached to it and
|
||||
the destructor returned -1. See <link
|
||||
linkend="talloc_set_destructor"><quote>talloc_set_destructor()</quote></link>
|
||||
for details on destructors.
|
||||
</para>
|
||||
<para>
|
||||
If this pointer has an additional parent when talloc_free() is
|
||||
called then the memory is not actually released, but instead the
|
||||
most recently established parent is destroyed. See <link
|
||||
linkend="talloc_reference"><quote>talloc_reference()</quote></link>
|
||||
for details on establishing additional parents.
|
||||
</para>
|
||||
<para>
|
||||
For more control on which parent is removed, see <link
|
||||
linkend="talloc_unlink"><quote>talloc_unlink()</quote></link>.
|
||||
</para>
|
||||
<para>
|
||||
talloc_free() operates recursively on its children.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_reference"><title>void *talloc_reference(const void *ctx, const void *ptr);</title>
|
||||
<para>
|
||||
The talloc_reference() function makes <emphasis
|
||||
role="italic">ctx</emphasis> an additional parent of <emphasis
|
||||
role="italic">ptr</emphasis>.
|
||||
</para>
|
||||
<para>
|
||||
The return value of talloc_reference() is always the original
|
||||
pointer <emphasis role="italic">ptr</emphasis>, unless talloc ran
|
||||
out of memory in creating the reference in which case it will
|
||||
return NULL (each additional reference consumes around 48 bytes
|
||||
of memory on intel x86 platforms).
|
||||
</para>
|
||||
<para>
|
||||
If <emphasis role="italic">ptr</emphasis> is NULL, then the
|
||||
function is a no-op, and simply returns NULL.
|
||||
</para>
|
||||
<para>
|
||||
After creating a reference you can free it in one of the
|
||||
following ways:
|
||||
</para>
|
||||
<para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>
|
||||
you can talloc_free() any parent of the original pointer.
|
||||
That will reduce the number of parents of this pointer by 1,
|
||||
and will cause this pointer to be freed if it runs out of
|
||||
parents.
|
||||
</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>
|
||||
you can talloc_free() the pointer itself. That will destroy
|
||||
the most recently established parent to the pointer and leave
|
||||
the pointer as a child of its current parent.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</para>
|
||||
<para>
|
||||
For more control on which parent to remove, see <link
|
||||
linkend="talloc_unlink"><quote>talloc_unlink()</quote></link>.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_unlink"><title>int talloc_unlink(const void *ctx, const void *ptr);</title>
|
||||
<para>
|
||||
The talloc_unlink() function removes a specific parent from
|
||||
<emphasis role="italic">ptr</emphasis>. The <emphasis
|
||||
role="italic">ctx</emphasis> passed must either be a context used
|
||||
in talloc_reference() with this pointer, or must be a direct
|
||||
parent of ptr.
|
||||
</para>
|
||||
<para>
|
||||
Note that if the parent has already been removed using
|
||||
talloc_free() then this function will fail and will return -1.
|
||||
Likewise, if <emphasis role="italic">ptr</emphasis> is NULL, then
|
||||
the function will make no modifications and return -1.
|
||||
</para>
|
||||
<para>
|
||||
Usually you can just use talloc_free() instead of
|
||||
talloc_unlink(), but sometimes it is useful to have the
|
||||
additional control on which parent is removed.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_set_destructor"><title>void talloc_set_destructor(const void *ptr, int (*destructor)(void *));</title>
|
||||
<para>
|
||||
The function talloc_set_destructor() sets the <emphasis
|
||||
role="italic">destructor</emphasis> for the pointer <emphasis
|
||||
role="italic">ptr</emphasis>. A <emphasis
|
||||
role="italic">destructor</emphasis> is a function that is called
|
||||
when the memory used by a pointer is about to be released. The
|
||||
destructor receives <emphasis role="italic">ptr</emphasis> as an
|
||||
argument, and should return 0 for success and -1 for failure.
|
||||
</para>
|
||||
<para>
|
||||
The <emphasis role="italic">destructor</emphasis> can do anything
|
||||
it wants to, including freeing other pieces of memory. A common
|
||||
use for destructors is to clean up operating system resources
|
||||
(such as open file descriptors) contained in the structure the
|
||||
destructor is placed on.
|
||||
</para>
|
||||
<para>
|
||||
You can only place one destructor on a pointer. If you need more
|
||||
than one destructor then you can create a zero-length child of
|
||||
the pointer and place an additional destructor on that.
|
||||
</para>
|
||||
<para>
|
||||
To remove a destructor call talloc_set_destructor() with NULL for
|
||||
the destructor.
|
||||
</para>
|
||||
<para>
|
||||
If your destructor attempts to talloc_free() the pointer that it
|
||||
is the destructor for then talloc_free() will return -1 and the
|
||||
free will be ignored. This would be a pointless operation
|
||||
anyway, as the destructor is only called when the memory is just
|
||||
about to go away.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>int talloc_increase_ref_count(const void *<emphasis role="italic">ptr</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_increase_ref_count(<emphasis
|
||||
role="italic">ptr</emphasis>) function is exactly equivalent to:
|
||||
</para>
|
||||
<programlisting>talloc_reference(NULL, ptr);</programlisting>
|
||||
<para>
|
||||
You can use either syntax, depending on which you think is
|
||||
clearer in your code.
|
||||
</para>
|
||||
<para>
|
||||
It returns 0 on success and -1 on failure.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>size_t talloc_reference_count(const void *<emphasis role="italic">ptr</emphasis>);</title>
|
||||
<para>
|
||||
Return the number of references to the pointer.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_set_name"><title>void talloc_set_name(const void *ptr, const char *fmt, ...);</title>
|
||||
<para>
|
||||
Each talloc pointer has a "name". The name is used principally
|
||||
for debugging purposes, although it is also possible to set and
|
||||
get the name on a pointer in as a way of "marking" pointers in
|
||||
your code.
|
||||
</para>
|
||||
<para>
|
||||
The main use for names on pointer is for "talloc reports". See
|
||||
<link
|
||||
linkend="talloc_report"><quote>talloc_report_depth_cb()</quote></link>,
|
||||
<link
|
||||
linkend="talloc_report"><quote>talloc_report_depth_file()</quote></link>,
|
||||
<link
|
||||
linkend="talloc_report"><quote>talloc_report()</quote></link>
|
||||
<link
|
||||
linkend="talloc_report"><quote>talloc_report()</quote></link>
|
||||
and <link
|
||||
linkend="talloc_report_full"><quote>talloc_report_full()</quote></link>
|
||||
for details. Also see <link
|
||||
linkend="talloc_enable_leak_report"><quote>talloc_enable_leak_report()</quote></link>
|
||||
and <link
|
||||
linkend="talloc_enable_leak_report_full"><quote>talloc_enable_leak_report_full()</quote></link>.
|
||||
</para>
|
||||
<para>
|
||||
The talloc_set_name() function allocates memory as a child of the
|
||||
pointer. It is logically equivalent to:
|
||||
</para>
|
||||
<programlisting>talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));</programlisting>
|
||||
<para>
|
||||
Note that multiple calls to talloc_set_name() will allocate more
|
||||
memory without releasing the name. All of the memory is released
|
||||
when the ptr is freed using talloc_free().
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void talloc_set_name_const(const void *<emphasis role="italic">ptr</emphasis>, const char *<emphasis role="italic">name</emphasis>);</title>
|
||||
<para>
|
||||
The function talloc_set_name_const() is just like
|
||||
talloc_set_name(), but it takes a string constant, and is much
|
||||
faster. It is extensively used by the "auto naming" macros, such
|
||||
as talloc_p().
|
||||
</para>
|
||||
<para>
|
||||
This function does not allocate any memory. It just copies the
|
||||
supplied pointer into the internal representation of the talloc
|
||||
ptr. This means you must not pass a <emphasis
|
||||
role="italic">name</emphasis> pointer to memory that will
|
||||
disappear before <emphasis role="italic">ptr</emphasis> is freed
|
||||
with talloc_free().
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_named(const void *<emphasis role="italic">ctx</emphasis>, size_t <emphasis role="italic">size</emphasis>, const char *<emphasis role="italic">fmt</emphasis>, ...);</title>
|
||||
<para>
|
||||
The talloc_named() function creates a named talloc pointer. It
|
||||
is equivalent to:
|
||||
</para>
|
||||
<programlisting>ptr = talloc_size(ctx, size);
|
||||
talloc_set_name(ptr, fmt, ....);</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_named_const(const void *<emphasis role="italic">ctx</emphasis>, size_t <emphasis role="italic">size</emphasis>, const char *<emphasis role="italic">name</emphasis>);</title>
|
||||
<para>
|
||||
This is equivalent to:
|
||||
</para>
|
||||
<programlisting>ptr = talloc_size(ctx, size);
|
||||
talloc_set_name_const(ptr, name);</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>const char *talloc_get_name(const void *<emphasis role="italic">ptr</emphasis>);</title>
|
||||
<para>
|
||||
This returns the current name for the given talloc pointer,
|
||||
<emphasis role="italic">ptr</emphasis>. See <link
|
||||
linkend="talloc_set_name"><quote>talloc_set_name()</quote></link>
|
||||
for details.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_init(const char *<emphasis role="italic">fmt</emphasis>, ...);</title>
|
||||
<para>
|
||||
This function creates a zero length named talloc context as a top
|
||||
level context. It is equivalent to:
|
||||
</para>
|
||||
<programlisting>talloc_named(NULL, 0, fmt, ...);</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_new(void *<emphasis role="italic">ctx</emphasis>);</title>
|
||||
<para>
|
||||
This is a utility macro that creates a new memory context hanging
|
||||
off an exiting context, automatically naming it "talloc_new:
|
||||
__location__" where __location__ is the source line it is called
|
||||
from. It is particularly useful for creating a new temporary
|
||||
working context.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>(<emphasis role="italic">type</emphasis> *)talloc_realloc(const void *<emphasis role="italic">ctx</emphasis>, void *<emphasis role="italic">ptr</emphasis>, <emphasis role="italic">type</emphasis>, <emphasis role="italic">count</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_realloc() macro changes the size of a talloc pointer.
|
||||
It has the following equivalences:
|
||||
</para>
|
||||
<programlisting>talloc_realloc(ctx, NULL, type, 1) ==> talloc(ctx, type);
|
||||
talloc_realloc(ctx, ptr, type, 0) ==> talloc_free(ptr);</programlisting>
|
||||
<para>
|
||||
The <emphasis role="italic">ctx</emphasis> argument is only used
|
||||
if <emphasis role="italic">ptr</emphasis> is not NULL, otherwise
|
||||
it is ignored.
|
||||
</para>
|
||||
<para>
|
||||
talloc_realloc() returns the new pointer, or NULL on failure.
|
||||
The call will fail either due to a lack of memory, or because the
|
||||
pointer has more than one parent (see <link
|
||||
linkend="talloc_reference"><quote>talloc_reference()</quote></link>).
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_realloc_size(const void *ctx, void *ptr, size_t size);</title>
|
||||
<para>
|
||||
the talloc_realloc_size() function is useful when the type is not
|
||||
known so the type-safe talloc_realloc() cannot be used.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>TYPE *talloc_steal(const void *<emphasis role="italic">new_ctx</emphasis>, const TYPE *<emphasis role="italic">ptr</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_steal() function changes the parent context of a
|
||||
talloc pointer. It is typically used when the context that the
|
||||
pointer is currently a child of is going to be freed and you wish
|
||||
to keep the memory for a longer time.
|
||||
</para>
|
||||
<para>
|
||||
The talloc_steal() function returns the pointer that you pass it.
|
||||
It does not have any failure modes.
|
||||
</para>
|
||||
<para>
|
||||
NOTE: It is possible to produce loops in the parent/child
|
||||
relationship if you are not careful with talloc_steal(). No
|
||||
guarantees are provided as to your sanity or the safety of your
|
||||
data if you do this.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>TYPE *talloc_move(const void *<emphasis role="italic">new_ctx</emphasis>, TYPE **<emphasis role="italic">ptr</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_move() function is a wrapper around
|
||||
talloc_steal() which zeros the source pointer after the
|
||||
move. This avoids a potential source of bugs where a
|
||||
programmer leaves a pointer in two structures, and uses the
|
||||
pointer from the old structure after it has been moved to a
|
||||
new one.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>size_t talloc_total_size(const void *<emphasis role="italic">ptr</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_total_size() function returns the total size in bytes
|
||||
used by this pointer and all child pointers. Mostly useful for
|
||||
debugging.
|
||||
</para>
|
||||
<para>
|
||||
Passing NULL is allowed, but it will only give a meaningful
|
||||
result if talloc_enable_leak_report() or
|
||||
talloc_enable_leak_report_full() has been called.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>size_t talloc_total_blocks(const void *<emphasis role="italic">ptr</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_total_blocks() function returns the total memory block
|
||||
count used by this pointer and all child pointers. Mostly useful
|
||||
for debugging.
|
||||
</para>
|
||||
<para>
|
||||
Passing NULL is allowed, but it will only give a meaningful
|
||||
result if talloc_enable_leak_report() or
|
||||
talloc_enable_leak_report_full() has been called.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_report"><title>void talloc_report(const void *ptr, FILE *f);</title>
|
||||
<para>
|
||||
The talloc_report() function prints a summary report of all
|
||||
memory used by <emphasis role="italic">ptr</emphasis>. One line
|
||||
of report is printed for each immediate child of ptr, showing the
|
||||
total memory and number of blocks used by that child.
|
||||
</para>
|
||||
<para>
|
||||
You can pass NULL for the pointer, in which case a report is
|
||||
printed for the top level memory context, but only if
|
||||
talloc_enable_leak_report() or talloc_enable_leak_report_full()
|
||||
has been called.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_report_full"><title>void talloc_report_full(const void *<emphasis role="italic">ptr</emphasis>, FILE *<emphasis role="italic">f</emphasis>);</title>
|
||||
<para>
|
||||
This provides a more detailed report than talloc_report(). It
|
||||
will recursively print the entire tree of memory referenced by
|
||||
the pointer. References in the tree are shown by giving the name
|
||||
of the pointer that is referenced.
|
||||
</para>
|
||||
<para>
|
||||
You can pass NULL for the pointer, in which case a report is
|
||||
printed for the top level memory context, but only if
|
||||
talloc_enable_leak_report() or talloc_enable_leak_report_full()
|
||||
has been called.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_report_depth_cb">
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>void <function>talloc_report_depth_cb</function></funcdef>
|
||||
<paramdef><parameter>const void *ptr</parameter></paramdef>
|
||||
<paramdef><parameter>int depth</parameter></paramdef>
|
||||
<paramdef><parameter>int max_depth</parameter></paramdef>
|
||||
<paramdef><parameter>void (*callback)(const void *ptr, int depth, int max_depth, int is_ref, void *priv)</parameter></paramdef>
|
||||
<paramdef><parameter>void *priv</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
<para>
|
||||
This provides a more flexible reports than talloc_report(). It
|
||||
will recursively call the callback for the entire tree of memory
|
||||
referenced by the pointer. References in the tree are passed with
|
||||
<emphasis role="italic">is_ref = 1</emphasis> and the pointer that is referenced.
|
||||
</para>
|
||||
<para>
|
||||
You can pass NULL for the pointer, in which case a report is
|
||||
printed for the top level memory context, but only if
|
||||
talloc_enable_leak_report() or talloc_enable_leak_report_full()
|
||||
has been called.
|
||||
</para>
|
||||
<para>
|
||||
The recursion is stopped when depth >= max_depth.
|
||||
max_depth = -1 means only stop at leaf nodes.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_report_depth_file">
|
||||
<funcsynopsis><funcprototype>
|
||||
<funcdef>void <function>talloc_report_depth_file</function></funcdef>
|
||||
<paramdef><parameter>const void *ptr</parameter></paramdef>
|
||||
<paramdef><parameter>int depth</parameter></paramdef>
|
||||
<paramdef><parameter>int max_depth</parameter></paramdef>
|
||||
<paramdef><parameter>FILE *f</parameter></paramdef>
|
||||
</funcprototype></funcsynopsis>
|
||||
<para>
|
||||
This provides a more flexible reports than talloc_report(). It
|
||||
will let you specify the depth and max_depth.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_enable_leak_report"><title>void talloc_enable_leak_report(void);</title>
|
||||
<para>
|
||||
This enables calling of talloc_report(NULL, stderr) when the
|
||||
program exits. In Samba4 this is enabled by using the
|
||||
--leak-report command line option.
|
||||
</para>
|
||||
<para>
|
||||
For it to be useful, this function must be called before any
|
||||
other talloc function as it establishes a "null context" that
|
||||
acts as the top of the tree. If you don't call this function
|
||||
first then passing NULL to talloc_report() or
|
||||
talloc_report_full() won't give you the full tree printout.
|
||||
</para>
|
||||
<para>
|
||||
Here is a typical talloc report:
|
||||
</para>
|
||||
<screen format="linespecific">talloc report on 'null_context' (total 267 bytes in 15 blocks)
|
||||
libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
|
||||
libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
|
||||
iconv(UTF8,CP850) contains 42 bytes in 2 blocks
|
||||
libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
|
||||
iconv(CP850,UTF8) contains 42 bytes in 2 blocks
|
||||
iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks
|
||||
iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks
|
||||
</screen>
|
||||
</refsect2>
|
||||
<refsect2 id="talloc_enable_leak_report_full"><title>void talloc_enable_leak_report_full(void);</title>
|
||||
<para>
|
||||
This enables calling of talloc_report_full(NULL, stderr) when the
|
||||
program exits. In Samba4 this is enabled by using the
|
||||
--leak-report-full command line option.
|
||||
</para>
|
||||
<para>
|
||||
For it to be useful, this function must be called before any
|
||||
other talloc function as it establishes a "null context" that
|
||||
acts as the top of the tree. If you don't call this function
|
||||
first then passing NULL to talloc_report() or
|
||||
talloc_report_full() won't give you the full tree printout.
|
||||
</para>
|
||||
<para>
|
||||
Here is a typical full report:
|
||||
</para>
|
||||
<screen format="linespecific">full talloc report on 'root' (total 18 bytes in 8 blocks)
|
||||
p1 contains 18 bytes in 7 blocks (ref 0)
|
||||
r1 contains 13 bytes in 2 blocks (ref 0)
|
||||
reference to: p2
|
||||
p2 contains 1 bytes in 1 blocks (ref 1)
|
||||
x3 contains 1 bytes in 1 blocks (ref 0)
|
||||
x2 contains 1 bytes in 1 blocks (ref 0)
|
||||
x1 contains 1 bytes in 1 blocks (ref 0)
|
||||
</screen>
|
||||
</refsect2>
|
||||
<refsect2><title>(<emphasis role="italic">type</emphasis> *)talloc_zero(const void *<emphasis role="italic">ctx</emphasis>, <emphasis role="italic">type</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_zero() macro is equivalent to:
|
||||
</para>
|
||||
<programlisting>ptr = talloc(ctx, type);
|
||||
if (ptr) memset(ptr, 0, sizeof(type));</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_zero_size(const void *<emphasis role="italic">ctx</emphasis>, size_t <emphasis role="italic">size</emphasis>)</title>
|
||||
<para>
|
||||
The talloc_zero_size() function is useful when you don't have a
|
||||
known type.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_memdup(const void *<emphasis role="italic">ctx</emphasis>, const void *<emphasis role="italic">p</emphasis>, size_t size);</title>
|
||||
<para>
|
||||
The talloc_memdup() function is equivalent to:
|
||||
</para>
|
||||
<programlisting>ptr = talloc_size(ctx, size);
|
||||
if (ptr) memcpy(ptr, p, size);</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>char *talloc_strdup(const void *<emphasis role="italic">ctx</emphasis>, const char *<emphasis role="italic">p</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_strdup() function is equivalent to:
|
||||
</para>
|
||||
<programlisting>ptr = talloc_size(ctx, strlen(p)+1);
|
||||
if (ptr) memcpy(ptr, p, strlen(p)+1);</programlisting>
|
||||
<para>
|
||||
This function sets the name of the new pointer to the passed
|
||||
string. This is equivalent to:
|
||||
</para>
|
||||
<programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>char *talloc_strndup(const void *<emphasis role="italic">t</emphasis>, const char *<emphasis role="italic">p</emphasis>, size_t <emphasis role="italic">n</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_strndup() function is the talloc equivalent of the C
|
||||
library function strndup(3).
|
||||
</para>
|
||||
<para>
|
||||
This function sets the name of the new pointer to the passed
|
||||
string. This is equivalent to:
|
||||
</para>
|
||||
<programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>char *talloc_append_string(const void *<emphasis role="italic">t</emphasis>, char *<emphasis role="italic">orig</emphasis>, const char *<emphasis role="italic">append</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_append_string() function appends the given formatted
|
||||
string to the given string.
|
||||
</para>
|
||||
<para>
|
||||
This function sets the name of the new pointer to the new
|
||||
string. This is equivalent to:
|
||||
</para>
|
||||
<programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>char *talloc_vasprintf(const void *<emphasis role="italic">t</emphasis>, const char *<emphasis role="italic">fmt</emphasis>, va_list <emphasis role="italic">ap</emphasis>);</title>
|
||||
<para>
|
||||
The talloc_vasprintf() function is the talloc equivalent of the C
|
||||
library function vasprintf(3).
|
||||
</para>
|
||||
<para>
|
||||
This function sets the name of the new pointer to the new
|
||||
string. This is equivalent to:
|
||||
</para>
|
||||
<programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>char *talloc_asprintf(const void *<emphasis role="italic">t</emphasis>, const char *<emphasis role="italic">fmt</emphasis>, ...);</title>
|
||||
<para>
|
||||
The talloc_asprintf() function is the talloc equivalent of the C
|
||||
library function asprintf(3).
|
||||
</para>
|
||||
<para>
|
||||
This function sets the name of the new pointer to the passed
|
||||
string. This is equivalent to:
|
||||
</para>
|
||||
<programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>char *talloc_asprintf_append(char *s, const char *fmt, ...);</title>
|
||||
<para>
|
||||
The talloc_asprintf_append() function appends the given formatted
|
||||
string to the given string.
|
||||
</para>
|
||||
<para>
|
||||
This function sets the name of the new pointer to the new
|
||||
string. This is equivalent to:
|
||||
</para>
|
||||
<programlisting>talloc_set_name_const(ptr, ptr)</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>(type *)talloc_array(const void *ctx, type, uint_t count);</title>
|
||||
<para>
|
||||
The talloc_array() macro is equivalent to:
|
||||
</para>
|
||||
<programlisting>(type *)talloc_size(ctx, sizeof(type) * count);</programlisting>
|
||||
<para>
|
||||
except that it provides integer overflow protection for the
|
||||
multiply, returning NULL if the multiply overflows.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_array_size(const void *ctx, size_t size, uint_t count);</title>
|
||||
<para>
|
||||
The talloc_array_size() function is useful when the type is not
|
||||
known. It operates in the same way as talloc_array(), but takes a
|
||||
size instead of a type.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count);</title>
|
||||
<para>
|
||||
The talloc_ptrtype() macro should be used when you have a pointer to an array
|
||||
and want to allocate memory of an array to point at with this pointer. When compiling
|
||||
with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
|
||||
and talloc_get_name() will return the current location in the source file.
|
||||
and not the type.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size)</title>
|
||||
<para>
|
||||
This is a non-macro version of talloc_realloc(), which is useful
|
||||
as libraries sometimes want a realloc function pointer. A
|
||||
realloc(3) implementation encapsulates the functionality of
|
||||
malloc(3), free(3) and realloc(3) in one call, which is why it is
|
||||
useful to be able to pass around a single function pointer.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_autofree_context(void);</title>
|
||||
<para>
|
||||
This is a handy utility function that returns a talloc context
|
||||
which will be automatically freed on program exit. This can be
|
||||
used to reduce the noise in memory leak reports.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>void *talloc_check_name(const void *ptr, const char *name);</title>
|
||||
<para>
|
||||
This function checks if a pointer has the specified <emphasis
|
||||
role="italic">name</emphasis>. If it does then the pointer is
|
||||
returned. It it doesn't then NULL is returned.
|
||||
</para>
|
||||
</refsect2>
|
||||
<refsect2><title>(type *)talloc_get_type(const void *ptr, type);</title>
|
||||
<para>
|
||||
This macro allows you to do type checking on talloc pointers. It
|
||||
is particularly useful for void* private pointers. It is
|
||||
equivalent to this:
|
||||
</para>
|
||||
<programlisting>(type *)talloc_check_name(ptr, #type)</programlisting>
|
||||
</refsect2>
|
||||
<refsect2><title>talloc_set_type(const void *ptr, type);</title>
|
||||
<para>
|
||||
This macro allows you to force the name of a pointer to be a
|
||||
particular <emphasis>type</emphasis>. This can be
|
||||
used in conjunction with talloc_get_type() to do type checking on
|
||||
void* pointers.
|
||||
</para>
|
||||
<para>
|
||||
It is equivalent to this:
|
||||
</para>
|
||||
<programlisting>talloc_set_name_const(ptr, #type)</programlisting>
|
||||
</refsect2>
|
||||
</refsect1>
|
||||
<refsect1><title>PERFORMANCE</title>
|
||||
<para>
|
||||
All the additional features of talloc(3) over malloc(3) do come at a
|
||||
price. We have a simple performance test in Samba4 that measures
|
||||
talloc() versus malloc() performance, and it seems that talloc() is
|
||||
about 10% slower than malloc() on my x86 Debian Linux box. For
|
||||
Samba, the great reduction in code complexity that we get by using
|
||||
talloc makes this worthwhile, especially as the total overhead of
|
||||
talloc/malloc in Samba is already quite small.
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1><title>SEE ALSO</title>
|
||||
<para>
|
||||
malloc(3), strndup(3), vasprintf(3), asprintf(3),
|
||||
<ulink url="http://talloc.samba.org/"/>
|
||||
</para>
|
||||
</refsect1>
|
||||
<refsect1><title>COPYRIGHT/LICENSE</title>
|
||||
<para>
|
||||
Copyright (C) Andrew Tridgell 2004
|
||||
</para>
|
||||
<para>
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or (at
|
||||
your option) any later version.
|
||||
</para>
|
||||
<para>
|
||||
This program is distributed in the hope that it will be useful, but
|
||||
WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
General Public License for more details.
|
||||
</para>
|
||||
<para>
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program; if not, see http://www.gnu.org/licenses/.
|
||||
</para>
|
||||
</refsect1>
|
||||
</refentry>
|
File diff suppressed because it is too large
Load Diff
@ -1,183 +0,0 @@
|
||||
#ifndef _TALLOC_H_
|
||||
#define _TALLOC_H_
|
||||
/*
|
||||
Unix SMB/CIFS implementation.
|
||||
Samba temporary memory allocation functions
|
||||
|
||||
Copyright (C) Andrew Tridgell 2004-2005
|
||||
Copyright (C) Stefan Metzmacher 2006
|
||||
|
||||
** NOTE! The following LGPL license applies to the talloc
|
||||
** library. This does NOT imply that all of Samba is released
|
||||
** under the LGPL
|
||||
|
||||
This library is free software; you can redistribute it and/or
|
||||
modify it under the terms of the GNU Lesser General Public
|
||||
License as published by the Free Software Foundation; either
|
||||
version 3 of the License, or (at your option) any later version.
|
||||
|
||||
This library is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
||||
Lesser General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Lesser General Public
|
||||
License along with this library; if not, see <http://www.gnu.org/licenses/>.
|
||||
*/
|
||||
|
||||
#include <stdlib.h>
|
||||
#include <stdio.h>
|
||||
#include <stdarg.h>
|
||||
|
||||
/* this is only needed for compatibility with the old talloc */
|
||||
typedef void TALLOC_CTX;
|
||||
|
||||
/*
|
||||
this uses a little trick to allow __LINE__ to be stringified
|
||||
*/
|
||||
#ifndef __location__
|
||||
#define __TALLOC_STRING_LINE1__(s) #s
|
||||
#define __TALLOC_STRING_LINE2__(s) __TALLOC_STRING_LINE1__(s)
|
||||
#define __TALLOC_STRING_LINE3__ __TALLOC_STRING_LINE2__(__LINE__)
|
||||
#define __location__ __FILE__ ":" __TALLOC_STRING_LINE3__
|
||||
#endif
|
||||
|
||||
#ifndef TALLOC_DEPRECATED
|
||||
#define TALLOC_DEPRECATED 0
|
||||
#endif
|
||||
|
||||
#ifndef PRINTF_ATTRIBUTE
|
||||
#if (__GNUC__ >= 3)
|
||||
/** Use gcc attribute to check printf fns. a1 is the 1-based index of
|
||||
* the parameter containing the format, and a2 the index of the first
|
||||
* argument. Note that some gcc 2.x versions don't handle this
|
||||
* properly **/
|
||||
#define PRINTF_ATTRIBUTE(a1, a2) __attribute__ ((format (__printf__, a1, a2)))
|
||||
#else
|
||||
#define PRINTF_ATTRIBUTE(a1, a2)
|
||||
#endif
|
||||
#endif
|
||||
|
||||
/* try to make talloc_set_destructor() and talloc_steal() type safe,
|
||||
if we have a recent gcc */
|
||||
#if (__GNUC__ >= 3)
|
||||
#define _TALLOC_TYPEOF(ptr) __typeof__(ptr)
|
||||
#define talloc_set_destructor(ptr, function) \
|
||||
do { \
|
||||
int (*_talloc_destructor_fn)(_TALLOC_TYPEOF(ptr)) = (function); \
|
||||
_talloc_set_destructor((ptr), (int (*)(void *))_talloc_destructor_fn); \
|
||||
} while(0)
|
||||
/* this extremely strange macro is to avoid some braindamaged warning
|
||||
stupidity in gcc 4.1.x */
|
||||
#define talloc_steal(ctx, ptr) ({ _TALLOC_TYPEOF(ptr) __talloc_steal_ret = (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr)); __talloc_steal_ret; })
|
||||
#else
|
||||
#define talloc_set_destructor(ptr, function) \
|
||||
_talloc_set_destructor((ptr), (int (*)(void *))(function))
|
||||
#define _TALLOC_TYPEOF(ptr) void *
|
||||
#define talloc_steal(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_steal((ctx),(ptr))
|
||||
#endif
|
||||
|
||||
#define talloc_reference(ctx, ptr) (_TALLOC_TYPEOF(ptr))_talloc_reference((ctx),(ptr))
|
||||
#define talloc_move(ctx, ptr) (_TALLOC_TYPEOF(*(ptr)))_talloc_move((ctx),(void *)(ptr))
|
||||
|
||||
/* useful macros for creating type checked pointers */
|
||||
#define talloc(ctx, type) (type *)talloc_named_const(ctx, sizeof(type), #type)
|
||||
#define talloc_size(ctx, size) talloc_named_const(ctx, size, __location__)
|
||||
#define talloc_ptrtype(ctx, ptr) (_TALLOC_TYPEOF(ptr))talloc_size(ctx, sizeof(*(ptr)))
|
||||
|
||||
#define talloc_new(ctx) talloc_named_const(ctx, 0, "talloc_new: " __location__)
|
||||
|
||||
#define talloc_zero(ctx, type) (type *)_talloc_zero(ctx, sizeof(type), #type)
|
||||
#define talloc_zero_size(ctx, size) _talloc_zero(ctx, size, __location__)
|
||||
|
||||
#define talloc_zero_array(ctx, type, count) (type *)_talloc_zero_array(ctx, sizeof(type), count, #type)
|
||||
#define talloc_array(ctx, type, count) (type *)_talloc_array(ctx, sizeof(type), count, #type)
|
||||
#define talloc_array_size(ctx, size, count) _talloc_array(ctx, size, count, __location__)
|
||||
#define talloc_array_ptrtype(ctx, ptr, count) (_TALLOC_TYPEOF(ptr))talloc_array_size(ctx, sizeof(*(ptr)), count)
|
||||
|
||||
#define talloc_realloc(ctx, p, type, count) (type *)_talloc_realloc_array(ctx, p, sizeof(type), count, #type)
|
||||
#define talloc_realloc_size(ctx, ptr, size) _talloc_realloc(ctx, ptr, size, __location__)
|
||||
|
||||
#define talloc_memdup(t, p, size) _talloc_memdup(t, p, size, __location__)
|
||||
|
||||
#define talloc_set_type(ptr, type) talloc_set_name_const(ptr, #type)
|
||||
#define talloc_get_type(ptr, type) (type *)talloc_check_name(ptr, #type)
|
||||
|
||||
#define talloc_find_parent_bytype(ptr, type) (type *)talloc_find_parent_byname(ptr, #type)
|
||||
|
||||
#if TALLOC_DEPRECATED
|
||||
#define talloc_zero_p(ctx, type) talloc_zero(ctx, type)
|
||||
#define talloc_p(ctx, type) talloc(ctx, type)
|
||||
#define talloc_array_p(ctx, type, count) talloc_array(ctx, type, count)
|
||||
#define talloc_realloc_p(ctx, p, type, count) talloc_realloc(ctx, p, type, count)
|
||||
#define talloc_destroy(ctx) talloc_free(ctx)
|
||||
#define talloc_append_string(c, s, a) (s?talloc_strdup_append(s,a):talloc_strdup(c, a))
|
||||
#endif
|
||||
|
||||
/* The following definitions come from talloc.c */
|
||||
void *_talloc(const void *context, size_t size);
|
||||
void *talloc_pool(const void *context, size_t size);
|
||||
void _talloc_set_destructor(const void *ptr, int (*destructor)(void *));
|
||||
int talloc_increase_ref_count(const void *ptr);
|
||||
size_t talloc_reference_count(const void *ptr);
|
||||
void *_talloc_reference(const void *context, const void *ptr);
|
||||
int talloc_unlink(const void *context, void *ptr);
|
||||
const char *talloc_set_name(const void *ptr, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
|
||||
void talloc_set_name_const(const void *ptr, const char *name);
|
||||
void *talloc_named(const void *context, size_t size,
|
||||
const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
|
||||
void *talloc_named_const(const void *context, size_t size, const char *name);
|
||||
const char *talloc_get_name(const void *ptr);
|
||||
void *talloc_check_name(const void *ptr, const char *name);
|
||||
void *talloc_parent(const void *ptr);
|
||||
const char *talloc_parent_name(const void *ptr);
|
||||
void *talloc_init(const char *fmt, ...) PRINTF_ATTRIBUTE(1,2);
|
||||
int talloc_free(void *ptr);
|
||||
void talloc_free_children(void *ptr);
|
||||
void *_talloc_realloc(const void *context, void *ptr, size_t size, const char *name);
|
||||
void *_talloc_steal(const void *new_ctx, const void *ptr);
|
||||
void *_talloc_move(const void *new_ctx, const void *pptr);
|
||||
size_t talloc_total_size(const void *ptr);
|
||||
size_t talloc_total_blocks(const void *ptr);
|
||||
void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
|
||||
void (*callback)(const void *ptr,
|
||||
int depth, int max_depth,
|
||||
int is_ref,
|
||||
void *private_data),
|
||||
void *private_data);
|
||||
void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
|
||||
void talloc_report_full(const void *ptr, FILE *f);
|
||||
void talloc_report(const void *ptr, FILE *f);
|
||||
void talloc_enable_null_tracking(void);
|
||||
void talloc_disable_null_tracking(void);
|
||||
void talloc_enable_leak_report(void);
|
||||
void talloc_enable_leak_report_full(void);
|
||||
void *_talloc_zero(const void *ctx, size_t size, const char *name);
|
||||
void *_talloc_memdup(const void *t, const void *p, size_t size, const char *name);
|
||||
void *_talloc_array(const void *ctx, size_t el_size, unsigned count, const char *name);
|
||||
void *_talloc_zero_array(const void *ctx, size_t el_size, unsigned count, const char *name);
|
||||
void *_talloc_realloc_array(const void *ctx, void *ptr, size_t el_size, unsigned count, const char *name);
|
||||
void *talloc_realloc_fn(const void *context, void *ptr, size_t size);
|
||||
void *talloc_autofree_context(void);
|
||||
size_t talloc_get_size(const void *ctx);
|
||||
void *talloc_find_parent_byname(const void *ctx, const char *name);
|
||||
void talloc_show_parents(const void *context, FILE *file);
|
||||
int talloc_is_parent(const void *context, const void *ptr);
|
||||
|
||||
char *talloc_strdup(const void *t, const char *p);
|
||||
char *talloc_strdup_append(char *s, const char *a);
|
||||
char *talloc_strdup_append_buffer(char *s, const char *a);
|
||||
|
||||
char *talloc_strndup(const void *t, const char *p, size_t n);
|
||||
char *talloc_strndup_append(char *s, const char *a, size_t n);
|
||||
char *talloc_strndup_append_buffer(char *s, const char *a, size_t n);
|
||||
|
||||
char *talloc_vasprintf(const void *t, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
|
||||
char *talloc_vasprintf_append(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
|
||||
char *talloc_vasprintf_append_buffer(char *s, const char *fmt, va_list ap) PRINTF_ATTRIBUTE(2,0);
|
||||
|
||||
char *talloc_asprintf(const void *t, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
|
||||
char *talloc_asprintf_append(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
|
||||
char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...) PRINTF_ATTRIBUTE(2,3);
|
||||
|
||||
#endif
|
@ -1,31 +0,0 @@
|
||||
/*
|
||||
Unix SMB/CIFS implementation.
|
||||
Copyright (C) Jelmer Vernooij <jelmer@samba.org> 2007
|
||||
|
||||
This program is free software; you can redistribute it and/or modify
|
||||
it under the terms of the GNU General Public License as published by
|
||||
the Free Software Foundation; either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU General Public License
|
||||
along with this program. If not, see <http://www.gnu.org/licenses/>.
|
||||
*/
|
||||
|
||||
/* Don't expose talloc contexts in Python code. Python does reference
|
||||
counting for us, so just create a new top-level talloc context.
|
||||
*/
|
||||
%typemap(in, numinputs=0, noblock=1) TALLOC_CTX * {
|
||||
$1 = NULL;
|
||||
}
|
||||
|
||||
%define %talloctype(TYPE)
|
||||
%nodefaultctor TYPE;
|
||||
%extend TYPE {
|
||||
~TYPE() { talloc_free($self); }
|
||||
}
|
||||
%enddef
|
@ -1,37 +0,0 @@
|
||||
TALLOC_OBJ = $(tallocdir)/talloc.o
|
||||
|
||||
TALLOC_SOLIB = libtalloc.$(SHLIBEXT).$(PACKAGE_VERSION)
|
||||
TALLOC_SONAME = libtalloc.$(SHLIBEXT).1
|
||||
|
||||
all:: libtalloc.a $(TALLOC_SOLIB) testsuite
|
||||
|
||||
testsuite:: $(LIBOBJ) testsuite.o
|
||||
$(CC) $(CFLAGS) -o testsuite testsuite.o $(LIBOBJ) $(LIBS)
|
||||
|
||||
libtalloc.a: $(LIBOBJ)
|
||||
ar -rv $@ $(LIBOBJ)
|
||||
@-ranlib $@
|
||||
|
||||
install:: all
|
||||
${INSTALLCMD} -d $(DESTDIR)$(libdir)
|
||||
${INSTALLCMD} -d $(DESTDIR)$(libdir)/pkgconfig
|
||||
${INSTALLCMD} -m 755 libtalloc.a $(DESTDIR)$(libdir)
|
||||
${INSTALLCMD} -m 755 $(TALLOC_SOLIB) $(DESTDIR)$(libdir)
|
||||
${INSTALLCMD} -d $(DESTDIR)${includedir}
|
||||
${INSTALLCMD} -m 644 $(srcdir)/talloc.h $(DESTDIR)$(includedir)
|
||||
${INSTALLCMD} -m 644 talloc.pc $(DESTDIR)$(libdir)/pkgconfig
|
||||
if [ -f talloc.3 ];then ${INSTALLCMD} -d $(DESTDIR)$(mandir)/man3; fi
|
||||
if [ -f talloc.3 ];then ${INSTALLCMD} -m 644 talloc.3 $(DESTDIR)$(mandir)/man3; fi
|
||||
which swig >/dev/null 2>&1 && ${INSTALLCMD} -d $(DESTDIR)`swig -swiglib` || true
|
||||
which swig >/dev/null 2>&1 && ${INSTALLCMD} -m 644 talloc.i $(DESTDIR)`swig -swiglib` || true
|
||||
|
||||
doc:: talloc.3 talloc.3.html
|
||||
|
||||
clean::
|
||||
rm -f *~ $(LIBOBJ) $(TALLOC_SOLIB) libtalloc.a testsuite testsuite.o *.gc?? talloc.3 talloc.3.html
|
||||
|
||||
test:: testsuite
|
||||
./testsuite
|
||||
|
||||
gcov::
|
||||
gcov talloc.c
|
@ -1,11 +0,0 @@
|
||||
prefix=@prefix@
|
||||
exec_prefix=@exec_prefix@
|
||||
libdir=@libdir@
|
||||
includedir=@includedir@
|
||||
|
||||
Name: talloc
|
||||
Description: A hierarchical pool based memory system with destructors
|
||||
Version: @PACKAGE_VERSION@
|
||||
Libs: -L${libdir} -ltalloc
|
||||
Cflags: -I${includedir}
|
||||
URL: http://talloc.samba.org/
|
@ -1,685 +0,0 @@
|
||||
Using talloc in Samba4
|
||||
----------------------
|
||||
|
||||
Andrew Tridgell
|
||||
September 2004
|
||||
|
||||
The most current version of this document is available at
|
||||
http://samba.org/ftp/unpacked/samba4/source/lib/talloc/talloc_guide.txt
|
||||
|
||||
If you are used to the "old" talloc from Samba3 before 3.0.20 then please read
|
||||
this carefully, as talloc has changed a lot. With 3.0.20 (or 3.0.14?) the
|
||||
Samba4 talloc has been ported back to Samba3, so this guide applies to both.
|
||||
|
||||
The new talloc is a hierarchical, reference counted memory pool system
|
||||
with destructors. Quite a mouthful really, but not too bad once you
|
||||
get used to it.
|
||||
|
||||
Perhaps the biggest change from Samba3 is that there is no distinction
|
||||
between a "talloc context" and a "talloc pointer". Any pointer
|
||||
returned from talloc() is itself a valid talloc context. This means
|
||||
you can do this:
|
||||
|
||||
struct foo *X = talloc(mem_ctx, struct foo);
|
||||
X->name = talloc_strdup(X, "foo");
|
||||
|
||||
and the pointer X->name would be a "child" of the talloc context "X"
|
||||
which is itself a child of mem_ctx. So if you do talloc_free(mem_ctx)
|
||||
then it is all destroyed, whereas if you do talloc_free(X) then just X
|
||||
and X->name are destroyed, and if you do talloc_free(X->name) then
|
||||
just the name element of X is destroyed.
|
||||
|
||||
If you think about this, then what this effectively gives you is an
|
||||
n-ary tree, where you can free any part of the tree with
|
||||
talloc_free().
|
||||
|
||||
If you find this confusing, then I suggest you run the testsuite to
|
||||
watch talloc in action. You may also like to add your own tests to
|
||||
testsuite.c to clarify how some particular situation is handled.
|
||||
|
||||
|
||||
Performance
|
||||
-----------
|
||||
|
||||
All the additional features of talloc() over malloc() do come at a
|
||||
price. We have a simple performance test in Samba4 that measures
|
||||
talloc() versus malloc() performance, and it seems that talloc() is
|
||||
about 4% slower than malloc() on my x86 Debian Linux box. For Samba,
|
||||
the great reduction in code complexity that we get by using talloc
|
||||
makes this worthwhile, especially as the total overhead of
|
||||
talloc/malloc in Samba is already quite small.
|
||||
|
||||
|
||||
talloc API
|
||||
----------
|
||||
|
||||
The following is a complete guide to the talloc API. Read it all at
|
||||
least twice.
|
||||
|
||||
Multi-threading
|
||||
---------------
|
||||
|
||||
talloc itself does not deal with threads. It is thread-safe (assuming
|
||||
the underlying "malloc" is), as long as each thread uses different
|
||||
memory contexts.
|
||||
If two threads uses the same context then they need to synchronize in
|
||||
order to be safe. In particular:
|
||||
- when using talloc_enable_leak_report(), giving directly NULL as a
|
||||
parent context implicitly refers to a hidden "null context" global
|
||||
variable, so this should not be used in a multi-threaded environment
|
||||
without proper synchronization ;
|
||||
- the context returned by talloc_autofree_context() is also global so
|
||||
shouldn't be used by several threads simultaneously without
|
||||
synchronization.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
(type *)talloc(const void *context, type);
|
||||
|
||||
The talloc() macro is the core of the talloc library. It takes a
|
||||
memory context and a type, and returns a pointer to a new area of
|
||||
memory of the given type.
|
||||
|
||||
The returned pointer is itself a talloc context, so you can use it as
|
||||
the context argument to more calls to talloc if you wish.
|
||||
|
||||
The returned pointer is a "child" of the supplied context. This means
|
||||
that if you talloc_free() the context then the new child disappears as
|
||||
well. Alternatively you can free just the child.
|
||||
|
||||
The context argument to talloc() can be NULL, in which case a new top
|
||||
level context is created.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_size(const void *context, size_t size);
|
||||
|
||||
The function talloc_size() should be used when you don't have a
|
||||
convenient type to pass to talloc(). Unlike talloc(), it is not type
|
||||
safe (as it returns a void *), so you are on your own for type checking.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
(typeof(ptr)) talloc_ptrtype(const void *ctx, ptr);
|
||||
|
||||
The talloc_ptrtype() macro should be used when you have a pointer and
|
||||
want to allocate memory to point at with this pointer. When compiling
|
||||
with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_size()
|
||||
and talloc_get_name() will return the current location in the source file.
|
||||
and not the type.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
int talloc_free(void *ptr);
|
||||
|
||||
The talloc_free() function frees a piece of talloc memory, and all its
|
||||
children. You can call talloc_free() on any pointer returned by
|
||||
talloc().
|
||||
|
||||
The return value of talloc_free() indicates success or failure, with 0
|
||||
returned for success and -1 for failure. The only possible failure
|
||||
condition is if the pointer had a destructor attached to it and the
|
||||
destructor returned -1. See talloc_set_destructor() for details on
|
||||
destructors.
|
||||
|
||||
If this pointer has an additional parent when talloc_free() is called
|
||||
then the memory is not actually released, but instead the most
|
||||
recently established parent is destroyed. See talloc_reference() for
|
||||
details on establishing additional parents.
|
||||
|
||||
For more control on which parent is removed, see talloc_unlink()
|
||||
|
||||
talloc_free() operates recursively on its children.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
int talloc_free_children(void *ptr);
|
||||
|
||||
The talloc_free_children() walks along the list of all children of a
|
||||
talloc context and talloc_free()s only the children, not the context
|
||||
itself.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_reference(const void *context, const void *ptr);
|
||||
|
||||
The talloc_reference() function makes "context" an additional parent
|
||||
of "ptr".
|
||||
|
||||
The return value of talloc_reference() is always the original pointer
|
||||
"ptr", unless talloc ran out of memory in creating the reference in
|
||||
which case it will return NULL (each additional reference consumes
|
||||
around 48 bytes of memory on intel x86 platforms).
|
||||
|
||||
If "ptr" is NULL, then the function is a no-op, and simply returns NULL.
|
||||
|
||||
After creating a reference you can free it in one of the following
|
||||
ways:
|
||||
|
||||
- you can talloc_free() any parent of the original pointer. That
|
||||
will reduce the number of parents of this pointer by 1, and will
|
||||
cause this pointer to be freed if it runs out of parents.
|
||||
|
||||
- you can talloc_free() the pointer itself. That will destroy the
|
||||
most recently established parent to the pointer and leave the
|
||||
pointer as a child of its current parent.
|
||||
|
||||
For more control on which parent to remove, see talloc_unlink()
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
int talloc_unlink(const void *context, const void *ptr);
|
||||
|
||||
The talloc_unlink() function removes a specific parent from ptr. The
|
||||
context passed must either be a context used in talloc_reference()
|
||||
with this pointer, or must be a direct parent of ptr.
|
||||
|
||||
Note that if the parent has already been removed using talloc_free()
|
||||
then this function will fail and will return -1. Likewise, if "ptr"
|
||||
is NULL, then the function will make no modifications and return -1.
|
||||
|
||||
Usually you can just use talloc_free() instead of talloc_unlink(), but
|
||||
sometimes it is useful to have the additional control on which parent
|
||||
is removed.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
|
||||
|
||||
The function talloc_set_destructor() sets the "destructor" for the
|
||||
pointer "ptr". A destructor is a function that is called when the
|
||||
memory used by a pointer is about to be released. The destructor
|
||||
receives the pointer as an argument, and should return 0 for success
|
||||
and -1 for failure.
|
||||
|
||||
The destructor can do anything it wants to, including freeing other
|
||||
pieces of memory. A common use for destructors is to clean up
|
||||
operating system resources (such as open file descriptors) contained
|
||||
in the structure the destructor is placed on.
|
||||
|
||||
You can only place one destructor on a pointer. If you need more than
|
||||
one destructor then you can create a zero-length child of the pointer
|
||||
and place an additional destructor on that.
|
||||
|
||||
To remove a destructor call talloc_set_destructor() with NULL for the
|
||||
destructor.
|
||||
|
||||
If your destructor attempts to talloc_free() the pointer that it is
|
||||
the destructor for then talloc_free() will return -1 and the free will
|
||||
be ignored. This would be a pointless operation anyway, as the
|
||||
destructor is only called when the memory is just about to go away.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
int talloc_increase_ref_count(const void *ptr);
|
||||
|
||||
The talloc_increase_ref_count(ptr) function is exactly equivalent to:
|
||||
|
||||
talloc_reference(NULL, ptr);
|
||||
|
||||
You can use either syntax, depending on which you think is clearer in
|
||||
your code.
|
||||
|
||||
It returns 0 on success and -1 on failure.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
size_t talloc_reference_count(const void *ptr);
|
||||
|
||||
Return the number of references to the pointer.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_set_name(const void *ptr, const char *fmt, ...);
|
||||
|
||||
Each talloc pointer has a "name". The name is used principally for
|
||||
debugging purposes, although it is also possible to set and get the
|
||||
name on a pointer in as a way of "marking" pointers in your code.
|
||||
|
||||
The main use for names on pointer is for "talloc reports". See
|
||||
talloc_report() and talloc_report_full() for details. Also see
|
||||
talloc_enable_leak_report() and talloc_enable_leak_report_full().
|
||||
|
||||
The talloc_set_name() function allocates memory as a child of the
|
||||
pointer. It is logically equivalent to:
|
||||
talloc_set_name_const(ptr, talloc_asprintf(ptr, fmt, ...));
|
||||
|
||||
Note that multiple calls to talloc_set_name() will allocate more
|
||||
memory without releasing the name. All of the memory is released when
|
||||
the ptr is freed using talloc_free().
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_set_name_const(const void *ptr, const char *name);
|
||||
|
||||
The function talloc_set_name_const() is just like talloc_set_name(),
|
||||
but it takes a string constant, and is much faster. It is extensively
|
||||
used by the "auto naming" macros, such as talloc_p().
|
||||
|
||||
This function does not allocate any memory. It just copies the
|
||||
supplied pointer into the internal representation of the talloc
|
||||
ptr. This means you must not pass a name pointer to memory that will
|
||||
disappear before the ptr is freed with talloc_free().
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_named(const void *context, size_t size, const char *fmt, ...);
|
||||
|
||||
The talloc_named() function creates a named talloc pointer. It is
|
||||
equivalent to:
|
||||
|
||||
ptr = talloc_size(context, size);
|
||||
talloc_set_name(ptr, fmt, ....);
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_named_const(const void *context, size_t size, const char *name);
|
||||
|
||||
This is equivalent to:
|
||||
|
||||
ptr = talloc_size(context, size);
|
||||
talloc_set_name_const(ptr, name);
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
const char *talloc_get_name(const void *ptr);
|
||||
|
||||
This returns the current name for the given talloc pointer. See
|
||||
talloc_set_name() for details.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_init(const char *fmt, ...);
|
||||
|
||||
This function creates a zero length named talloc context as a top
|
||||
level context. It is equivalent to:
|
||||
|
||||
talloc_named(NULL, 0, fmt, ...);
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_new(void *ctx);
|
||||
|
||||
This is a utility macro that creates a new memory context hanging
|
||||
off an exiting context, automatically naming it "talloc_new: __location__"
|
||||
where __location__ is the source line it is called from. It is
|
||||
particularly useful for creating a new temporary working context.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
(type *)talloc_realloc(const void *context, void *ptr, type, count);
|
||||
|
||||
The talloc_realloc() macro changes the size of a talloc
|
||||
pointer. The "count" argument is the number of elements of type "type"
|
||||
that you want the resulting pointer to hold.
|
||||
|
||||
talloc_realloc() has the following equivalences:
|
||||
|
||||
talloc_realloc(context, NULL, type, 1) ==> talloc(context, type);
|
||||
talloc_realloc(context, NULL, type, N) ==> talloc_array(context, type, N);
|
||||
talloc_realloc(context, ptr, type, 0) ==> talloc_free(ptr);
|
||||
|
||||
The "context" argument is only used if "ptr" is NULL, otherwise it is
|
||||
ignored.
|
||||
|
||||
talloc_realloc() returns the new pointer, or NULL on failure. The call
|
||||
will fail either due to a lack of memory, or because the pointer has
|
||||
more than one parent (see talloc_reference()).
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_realloc_size(const void *context, void *ptr, size_t size);
|
||||
|
||||
the talloc_realloc_size() function is useful when the type is not
|
||||
known so the typesafe talloc_realloc() cannot be used.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_steal(const void *new_ctx, const void *ptr);
|
||||
|
||||
The talloc_steal() function changes the parent context of a talloc
|
||||
pointer. It is typically used when the context that the pointer is
|
||||
currently a child of is going to be freed and you wish to keep the
|
||||
memory for a longer time.
|
||||
|
||||
The talloc_steal() function returns the pointer that you pass it. It
|
||||
does not have any failure modes.
|
||||
|
||||
NOTE: It is possible to produce loops in the parent/child relationship
|
||||
if you are not careful with talloc_steal(). No guarantees are provided
|
||||
as to your sanity or the safety of your data if you do this.
|
||||
|
||||
talloc_steal (new_ctx, NULL) will return NULL with no sideeffects.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
size_t talloc_total_size(const void *ptr);
|
||||
|
||||
The talloc_total_size() function returns the total size in bytes used
|
||||
by this pointer and all child pointers. Mostly useful for debugging.
|
||||
|
||||
Passing NULL is allowed, but it will only give a meaningful result if
|
||||
talloc_enable_leak_report() or talloc_enable_leak_report_full() has
|
||||
been called.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
size_t talloc_total_blocks(const void *ptr);
|
||||
|
||||
The talloc_total_blocks() function returns the total memory block
|
||||
count used by this pointer and all child pointers. Mostly useful for
|
||||
debugging.
|
||||
|
||||
Passing NULL is allowed, but it will only give a meaningful result if
|
||||
talloc_enable_leak_report() or talloc_enable_leak_report_full() has
|
||||
been called.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_report_depth_cb(const void *ptr, int depth, int max_depth,
|
||||
void (*callback)(const void *ptr,
|
||||
int depth, int max_depth,
|
||||
int is_ref,
|
||||
void *priv),
|
||||
void *priv);
|
||||
|
||||
This provides a more flexible reports than talloc_report(). It
|
||||
will recursively call the callback for the entire tree of memory
|
||||
referenced by the pointer. References in the tree are passed with
|
||||
is_ref = 1 and the pointer that is referenced.
|
||||
|
||||
You can pass NULL for the pointer, in which case a report is
|
||||
printed for the top level memory context, but only if
|
||||
talloc_enable_leak_report() or talloc_enable_leak_report_full()
|
||||
has been called.
|
||||
|
||||
The recursion is stopped when depth >= max_depth.
|
||||
max_depth = -1 means only stop at leaf nodes.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_report_depth_file(const void *ptr, int depth, int max_depth, FILE *f);
|
||||
|
||||
This provides a more flexible reports than talloc_report(). It
|
||||
will let you specify the depth and max_depth.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_report(const void *ptr, FILE *f);
|
||||
|
||||
The talloc_report() function prints a summary report of all memory
|
||||
used by ptr. One line of report is printed for each immediate child of
|
||||
ptr, showing the total memory and number of blocks used by that child.
|
||||
|
||||
You can pass NULL for the pointer, in which case a report is printed
|
||||
for the top level memory context, but only if
|
||||
talloc_enable_leak_report() or talloc_enable_leak_report_full() has
|
||||
been called.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_report_full(const void *ptr, FILE *f);
|
||||
|
||||
This provides a more detailed report than talloc_report(). It will
|
||||
recursively print the ensire tree of memory referenced by the
|
||||
pointer. References in the tree are shown by giving the name of the
|
||||
pointer that is referenced.
|
||||
|
||||
You can pass NULL for the pointer, in which case a report is printed
|
||||
for the top level memory context, but only if
|
||||
talloc_enable_leak_report() or talloc_enable_leak_report_full() has
|
||||
been called.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_enable_leak_report(void);
|
||||
|
||||
This enables calling of talloc_report(NULL, stderr) when the program
|
||||
exits. In Samba4 this is enabled by using the --leak-report command
|
||||
line option.
|
||||
|
||||
For it to be useful, this function must be called before any other
|
||||
talloc function as it establishes a "null context" that acts as the
|
||||
top of the tree. If you don't call this function first then passing
|
||||
NULL to talloc_report() or talloc_report_full() won't give you the
|
||||
full tree printout.
|
||||
|
||||
Here is a typical talloc report:
|
||||
|
||||
talloc report on 'null_context' (total 267 bytes in 15 blocks)
|
||||
libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
|
||||
libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
|
||||
iconv(UTF8,CP850) contains 42 bytes in 2 blocks
|
||||
libcli/auth/spnego_parse.c:55 contains 31 bytes in 2 blocks
|
||||
iconv(CP850,UTF8) contains 42 bytes in 2 blocks
|
||||
iconv(UTF8,UTF-16LE) contains 45 bytes in 2 blocks
|
||||
iconv(UTF-16LE,UTF8) contains 45 bytes in 2 blocks
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_enable_leak_report_full(void);
|
||||
|
||||
This enables calling of talloc_report_full(NULL, stderr) when the
|
||||
program exits. In Samba4 this is enabled by using the
|
||||
--leak-report-full command line option.
|
||||
|
||||
For it to be useful, this function must be called before any other
|
||||
talloc function as it establishes a "null context" that acts as the
|
||||
top of the tree. If you don't call this function first then passing
|
||||
NULL to talloc_report() or talloc_report_full() won't give you the
|
||||
full tree printout.
|
||||
|
||||
Here is a typical full report:
|
||||
|
||||
full talloc report on 'root' (total 18 bytes in 8 blocks)
|
||||
p1 contains 18 bytes in 7 blocks (ref 0)
|
||||
r1 contains 13 bytes in 2 blocks (ref 0)
|
||||
reference to: p2
|
||||
p2 contains 1 bytes in 1 blocks (ref 1)
|
||||
x3 contains 1 bytes in 1 blocks (ref 0)
|
||||
x2 contains 1 bytes in 1 blocks (ref 0)
|
||||
x1 contains 1 bytes in 1 blocks (ref 0)
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_enable_null_tracking(void);
|
||||
|
||||
This enables tracking of the NULL memory context without enabling leak
|
||||
reporting on exit. Useful for when you want to do your own leak
|
||||
reporting call via talloc_report_null_full();
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void talloc_disable_null_tracking(void);
|
||||
|
||||
This disables tracking of the NULL memory context.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
(type *)talloc_zero(const void *ctx, type);
|
||||
|
||||
The talloc_zero() macro is equivalent to:
|
||||
|
||||
ptr = talloc(ctx, type);
|
||||
if (ptr) memset(ptr, 0, sizeof(type));
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_zero_size(const void *ctx, size_t size)
|
||||
|
||||
The talloc_zero_size() function is useful when you don't have a known type
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_memdup(const void *ctx, const void *p, size_t size);
|
||||
|
||||
The talloc_memdup() function is equivalent to:
|
||||
|
||||
ptr = talloc_size(ctx, size);
|
||||
if (ptr) memcpy(ptr, p, size);
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
char *talloc_strdup(const void *ctx, const char *p);
|
||||
|
||||
The talloc_strdup() function is equivalent to:
|
||||
|
||||
ptr = talloc_size(ctx, strlen(p)+1);
|
||||
if (ptr) memcpy(ptr, p, strlen(p)+1);
|
||||
|
||||
This functions sets the name of the new pointer to the passed
|
||||
string. This is equivalent to:
|
||||
talloc_set_name_const(ptr, ptr)
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
char *talloc_strndup(const void *t, const char *p, size_t n);
|
||||
|
||||
The talloc_strndup() function is the talloc equivalent of the C
|
||||
library function strndup()
|
||||
|
||||
This functions sets the name of the new pointer to the passed
|
||||
string. This is equivalent to:
|
||||
talloc_set_name_const(ptr, ptr)
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
char *talloc_append_string(const void *t, char *orig, const char *append);
|
||||
|
||||
The talloc_append_string() function appends the given formatted
|
||||
string to the given string.
|
||||
|
||||
This function sets the name of the new pointer to the new
|
||||
string. This is equivalent to:
|
||||
talloc_set_name_const(ptr, ptr)
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
char *talloc_vasprintf(const void *t, const char *fmt, va_list ap);
|
||||
|
||||
The talloc_vasprintf() function is the talloc equivalent of the C
|
||||
library function vasprintf()
|
||||
|
||||
This functions sets the name of the new pointer to the new
|
||||
string. This is equivalent to:
|
||||
talloc_set_name_const(ptr, ptr)
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
char *talloc_asprintf(const void *t, const char *fmt, ...);
|
||||
|
||||
The talloc_asprintf() function is the talloc equivalent of the C
|
||||
library function asprintf()
|
||||
|
||||
This functions sets the name of the new pointer to the new
|
||||
string. This is equivalent to:
|
||||
talloc_set_name_const(ptr, ptr)
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
char *talloc_asprintf_append(char *s, const char *fmt, ...);
|
||||
|
||||
The talloc_asprintf_append() function appends the given formatted
|
||||
string to the given string.
|
||||
Use this varient when the string in the current talloc buffer may
|
||||
have been truncated in length.
|
||||
|
||||
This functions sets the name of the new pointer to the new
|
||||
string. This is equivalent to:
|
||||
talloc_set_name_const(ptr, ptr)
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
char *talloc_asprintf_append_buffer(char *s, const char *fmt, ...);
|
||||
|
||||
The talloc_asprintf_append() function appends the given formatted
|
||||
string to the end of the currently allocated talloc buffer.
|
||||
Use this varient when the string in the current talloc buffer has
|
||||
not been changed.
|
||||
|
||||
This functions sets the name of the new pointer to the new
|
||||
string. This is equivalent to:
|
||||
talloc_set_name_const(ptr, ptr)
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
((type *)talloc_array(const void *ctx, type, uint_t count);
|
||||
|
||||
The talloc_array() macro is equivalent to:
|
||||
|
||||
(type *)talloc_size(ctx, sizeof(type) * count);
|
||||
|
||||
except that it provides integer overflow protection for the multiply,
|
||||
returning NULL if the multiply overflows.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_array_size(const void *ctx, size_t size, uint_t count);
|
||||
|
||||
The talloc_array_size() function is useful when the type is not
|
||||
known. It operates in the same way as talloc_array(), but takes a size
|
||||
instead of a type.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count);
|
||||
|
||||
The talloc_ptrtype() macro should be used when you have a pointer to an array
|
||||
and want to allocate memory of an array to point at with this pointer. When compiling
|
||||
with gcc >= 3 it is typesafe. Note this is a wrapper of talloc_array_size()
|
||||
and talloc_get_name() will return the current location in the source file.
|
||||
and not the type.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_realloc_fn(const void *ctx, void *ptr, size_t size);
|
||||
|
||||
This is a non-macro version of talloc_realloc(), which is useful
|
||||
as libraries sometimes want a ralloc function pointer. A realloc()
|
||||
implementation encapsulates the functionality of malloc(), free() and
|
||||
realloc() in one call, which is why it is useful to be able to pass
|
||||
around a single function pointer.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_autofree_context(void);
|
||||
|
||||
This is a handy utility function that returns a talloc context
|
||||
which will be automatically freed on program exit. This can be used
|
||||
to reduce the noise in memory leak reports.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_check_name(const void *ptr, const char *name);
|
||||
|
||||
This function checks if a pointer has the specified name. If it does
|
||||
then the pointer is returned. It it doesn't then NULL is returned.
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
(type *)talloc_get_type(const void *ptr, type);
|
||||
|
||||
This macro allows you to do type checking on talloc pointers. It is
|
||||
particularly useful for void* private pointers. It is equivalent to
|
||||
this:
|
||||
|
||||
(type *)talloc_check_name(ptr, #type)
|
||||
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
talloc_set_type(const void *ptr, type);
|
||||
|
||||
This macro allows you to force the name of a pointer to be a
|
||||
particular type. This can be used in conjunction with
|
||||
talloc_get_type() to do type checking on void* pointers.
|
||||
|
||||
It is equivalent to this:
|
||||
talloc_set_name_const(ptr, #type)
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
talloc_get_size(const void *ctx);
|
||||
|
||||
This function lets you know the amount of memory alloced so far by
|
||||
this context. It does NOT account for subcontext memory.
|
||||
This can be used to calculate the size of an array.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
void *talloc_find_parent_byname(const void *ctx, const char *name);
|
||||
|
||||
Find a parent memory context of the current context that has the given
|
||||
name. This can be very useful in complex programs where it may be
|
||||
difficult to pass all information down to the level you need, but you
|
||||
know the structure you want is a parent of another context.
|
||||
|
||||
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
|
||||
(type *)talloc_find_parent_bytype(ctx, type);
|
||||
|
||||
Like talloc_find_parent_byname() but takes a type, making it typesafe.
|
||||
|
File diff suppressed because it is too large
Load Diff
@ -1,46 +0,0 @@
|
||||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
|
||||
<HTML>
|
||||
<HEAD>
|
||||
<TITLE>talloc</TITLE>
|
||||
</HEAD>
|
||||
<BODY BGCOLOR="#ffffff" TEXT="#000000" VLINK="#292555" LINK="#292555" ALINK="#cc0033">
|
||||
|
||||
<h1>talloc</h1>
|
||||
|
||||
talloc is a hierarchical pool based memory allocator with
|
||||
destructors. It is the core memory allocator used in Samba4, and has
|
||||
made a huge difference in many aspects of Samba4 development.<p>
|
||||
|
||||
To get started with talloc, I would recommend you read the <a
|
||||
href="http://samba.org/ftp/unpacked/talloc/talloc_guide.txt">talloc guide</a>.
|
||||
|
||||
<h2>Discussion and bug reports</h2>
|
||||
|
||||
talloc does not currently have its own mailing list or bug tracking
|
||||
system. For now, please use the <a
|
||||
href="https://lists.samba.org/mailman/listinfo/samba-technical">samba-technical</a>
|
||||
mailing list, and the <a href="http://bugzilla.samba.org/">Samba
|
||||
bugzilla</a> bug tracking system.
|
||||
|
||||
<h2>Download</h2>
|
||||
|
||||
You can download the latest release either via rsync or git.<br>
|
||||
<br>
|
||||
To fetch via git see the following guide:<br>
|
||||
<a href="http://wiki.samba.org/index.php/Using_Git_for_Samba_Development">Using Git for Samba Development</a><br>
|
||||
Once you have cloned the tree switch to the v4-0-test branch and cd into the source/lib/talloc directory.<br>
|
||||
<br>
|
||||
To fetch via rsync use this command:
|
||||
|
||||
<pre>
|
||||
rsync -Pavz samba.org::ftp/unpacked/talloc .
|
||||
</pre>
|
||||
|
||||
<hr>
|
||||
<tiny>
|
||||
<a href="http://samba.org/~tridge/">Andrew Tridgell</a><br>
|
||||
talloc AT tridgell.net
|
||||
</tiny>
|
||||
|
||||
</BODY>
|
||||
</HTML>
|
@ -20,7 +20,7 @@ PRIVATE_DEPENDENCIES = \
|
||||
|
||||
TORTURE_LOCAL_OBJ_FILES = \
|
||||
$(torturesrcdir)/../lib/charset/tests/iconv.o \
|
||||
$(torturesrcdir)/../lib/talloc/testsuite.o \
|
||||
$(torturesrcdir)/../../talloc/testsuite.o \
|
||||
$(torturesrcdir)/../lib/replace/test/getifaddrs.o \
|
||||
$(torturesrcdir)/../lib/replace/test/os2_delete.o \
|
||||
$(torturesrcdir)/../lib/replace/test/strptime.o \
|
||||
|
@ -1,7 +1,7 @@
|
||||
[LIBRARY::LIBTALLOC]
|
||||
OUTPUT_TYPE = MERGED_OBJ
|
||||
CFLAGS = -Ilib/talloc
|
||||
CFLAGS = -I$(tallocsrcdir)
|
||||
|
||||
LIBTALLOC_OBJ_FILES = lib/talloc/talloc.o
|
||||
LIBTALLOC_OBJ_FILES = $(tallocsrcdir)/talloc.o
|
||||
|
||||
MANPAGES += $(tallocdir)/talloc.3
|
Loading…
Reference in New Issue
Block a user