From 169f12940462da90d6cdbbd1c8f170fa978d959a Mon Sep 17 00:00:00 2001 From: Andrew Tridgell Date: Wed, 2 May 2007 07:32:04 +1000 Subject: merge latest versions of lib/replace, lib/talloc, lib/tdb and lib/events into ctdb bzr tree (This used to be ctdb commit eaea8a9fa8d2f5e08f3af619fa1008a663f39053) --- ctdb/lib/talloc/talloc.3.html | 78 +++++++++++++++++++++---------------------- 1 file changed, 39 insertions(+), 39 deletions(-) (limited to 'ctdb/lib/talloc/talloc.3.html') diff --git a/ctdb/lib/talloc/talloc.3.html b/ctdb/lib/talloc/talloc.3.html index 160afa03e4..7d0129d30c 100644 --- a/ctdb/lib/talloc/talloc.3.html +++ b/ctdb/lib/talloc/talloc.3.html @@ -1,4 +1,4 @@ -talloc

Name

talloc — hierarchical reference counted memory pool system with destructors

Synopsis

#include <talloc/talloc.h>

DESCRIPTION

+talloc

Name

talloc — hierarchical reference counted memory pool system with destructors

Synopsis

#include <talloc/talloc.h>

DESCRIPTION

If you are used to talloc from Samba3 then please read this carefully, as talloc has changed a lot.

@@ -30,10 +30,10 @@ If you find this confusing, then I suggest you run the testsuite program 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. -

TALLOC API

+

TALLOC API

The following is a complete guide to the talloc API. Read it all at least twice. -

(type *)talloc(const void *ctx, type);

+

(type *)talloc(const void *ctx, type);

The talloc() macro is the core of the talloc library. It takes a memory ctx and a type, and returns a pointer to a new area of memory of the given type. @@ -48,18 +48,18 @@

The ctx argument to talloc() can be NULL, in which case a new top level context is created. -

void *talloc_size(const void *ctx, size_t size);

+

void *talloc_size(const void *ctx, 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);

+

(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);

+

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(). @@ -143,14 +143,14 @@ 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);

+

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);

+

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 @@ -173,7 +173,7 @@ 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);

+

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 @@ -184,27 +184,27 @@ ptr. This means you must not pass a name pointer to memory that will disappear before ptr is freed with talloc_free(). -

void *talloc_named(const void *ctx, size_t size, const char *fmt, ...);

+

void *talloc_named(const void *ctx, size_t size, const char *fmt, ...);

The talloc_named() function creates a named talloc pointer. It is equivalent to: 

ptr = talloc_size(ctx, size);
-talloc_set_name(ptr, fmt, ....);

void *talloc_named_const(const void *ctx, size_t size, const char *name);

+talloc_set_name(ptr, fmt, ....);

void *talloc_named_const(const void *ctx, size_t size, const char *name);

This is equivalent to: 

ptr = talloc_size(ctx, size);
-talloc_set_name_const(ptr, name);

const char *talloc_get_name(const void *ptr);

+talloc_set_name_const(ptr, name);

const char *talloc_get_name(const void *ptr);

This returns the current name for the given talloc pointer, ptr. See “talloc_set_name()” for details. -

void *talloc_init(const char *fmt, ...);

+

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);

+ 

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 *ctx, void *ptr, type, count);

+

(type *)talloc_realloc(const void *ctx, void *ptr, type, count);

The talloc_realloc() macro changes the size of a talloc pointer. It has the following equivalences: 

talloc_realloc(ctx, NULL, type, 1) ==> talloc(ctx, type);
@@ -216,10 +216,10 @@ talloc_realloc(ctx, ptr, type, 0)  ==> talloc_free(ptr);

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 *ctx, void *ptr, size_t size);

+

void *talloc_realloc_size(const void *ctx, void *ptr, size_t size);

the talloc_realloc_size() function is useful when the type is not known so the type-safe talloc_realloc() cannot be used. -

TYPE *talloc_steal(const void *new_ctx, const TYPE *ptr);

+

TYPE *talloc_steal(const void *new_ctx, const TYPE *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 @@ -232,14 +232,14 @@ talloc_realloc(ctx, ptr, type, 0) ==> talloc_free(ptr);

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. -

TYPE *talloc_move(const void *new_ctx, TYPE **ptr);

+

TYPE *talloc_move(const void *new_ctx, TYPE **ptr);

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. -

size_t talloc_total_size(const void *ptr);

+

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. @@ -247,7 +247,7 @@ talloc_realloc(ctx, ptr, type, 0) ==> talloc_free(ptr);

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);

+

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. @@ -331,79 +331,79 @@ p1 contains 18 bytes in 7 blocks (ref 0) 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) -

(type *)talloc_zero(const void *ctx, type);

+

(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)

+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);

+

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);

+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 function 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);

+ 

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(3).

This function sets the name of the new pointer to the passed string. This is equivalent to: - 

talloc_set_name_const(ptr, ptr)

char *talloc_vasprintf(const void *t, const char *fmt, va_list ap);

+ 

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(3). -

char *talloc_asprintf(const void *t, const char *fmt, ...);

+

char *talloc_asprintf(const void *t, const char *fmt, ...);

The talloc_asprintf() function is the talloc equivalent of the C library function asprintf(3).

This function sets the name of the new pointer to the passed string. This is equivalent to: - 

talloc_set_name_const(ptr, ptr)

char *talloc_asprintf_append(char *s, const char *fmt, ...);

+ 

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. -

(type *)talloc_array(const void *ctx, type, uint_t count);

+

(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);

+

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);

+

(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)

+

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 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. -

void *talloc_autofree_context(void);

+

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);

+

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);

+

(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);

+ 

(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)

PERFORMANCE

+ 

talloc_set_name_const(ptr, #type)

PERFORMANCE

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 @@ -411,10 +411,10 @@ if (ptr) memcpy(ptr, p, strlen(p)+1);

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. -

SEE ALSO

+

SEE ALSO

malloc(3), strndup(3), vasprintf(3), asprintf(3), http://talloc.samba.org/ -

COPYRIGHT/LICENSE

+

COPYRIGHT/LICENSE

Copyright (C) Andrew Tridgell 2004

This program is free software; you can redistribute it and/or modify -- cgit