← Back to branch summary

~ubuntu-branches/ubuntu/vivid/samba/vivid

« back to all changes in this revision

Viewing changes to lib/talloc/talloc_guide.txt

  • Committer: Package Import Robot
  • Author(s): Chuck Short
  • Date: 2011-12-21 13:18:04 UTC
  • mfrom: (0.39.21 sid)
  • Revision ID: package-import@ubuntu.com-20111221131804-xtlr39wx6njehxxr
Tags: 2:3.6.1-3ubuntu1
* Merge from Debian testing.  Remaining changes:
  + debian/patches/VERSION.patch:
    - set SAMBA_VERSION_SUFFIX to Ubuntu.
  + debian/patches/error-trans.fix-276472:
    - Add the translation of Unix Error code -ENOTSUP to NT Error Code
    - NT_STATUS_NOT_SUPPORTED to prevent the Permission denied error.
  + debian/smb.conf:
    - add "(Samba, Ubuntu)" to server string.
    - comment out the default [homes] share, and add a comment about
      "valid users = %S" to show users how to restrict access to
      \\server\username to only username.
    - Set 'usershare allow guests', so that usershare admins are 
      allowed to create public shares in addition to authenticated
      ones.
    - add map to guest = Bad user, maps bad username to guest access.
  + debian/samba-common.config:
    - Do not change priority to high if dhclient3 is installed.
    - Use priority medium instead of high for the workgroup question.
  + debian/control:
    - Don't build against or suggest ctdb.
    - Add dependency on samba-common-bin to samba.
  + Add ufw integration:
    - Created debian/samba.ufw.profile
    - debian/rules, debian/samba.dirs, debian/samba.files: install
      profile
    - debian/control: have samba suggest ufw
  + Add apport hook:
    - Created debian/source_samba.py.
    - debian/rules, debian/samba.dirs, debian/samba-common-bin.files: install
  + Switch to upstart:
    - Add debian/samba.{nmbd,smbd}.upstart.
  + debian/samba.logrotate, debian/samba-common.dhcp, debian/samba.if-up:
    - Make them upstart compatible
  + debian/samba.postinst: 
    - Avoid scary pdbedit warnings on first import.
  + debian/samba-common.postinst: Add more informative error message for
    the case where smb.conf was manually deleted
  + debian/patches/fix-debuglevel-name-conflict.patch: don't use 'debug_level'
    as a global variable name in an NSS module 
  + Dropped:
    - debian/patches/error-trans.fix-276472
    - debian/patches/fix-debuglevel-name-conflict.patch

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/talloc/talloc_guide.txt
26
26
  X->name = talloc_strdup(X, "foo");
27
27
 
28
28
and the pointer X->name would be a "child" of the talloc context "X"
29
 
which is itself a child of mem_ctx. So if you do talloc_free(mem_ctx)
 
29
which is itself a child of "mem_ctx". So if you do talloc_free(mem_ctx)
30
30
then it is all destroyed, whereas if you do talloc_free(X) then just X
31
31
and X->name are destroyed, and if you do talloc_free(X->name) then
32
32
just the name element of X is destroyed.
64
64
talloc itself does not deal with threads. It is thread-safe (assuming  
65
65
the underlying "malloc" is), as long as each thread uses different  
66
66
memory contexts.
67
 
If two threads uses the same context then they need to synchronize in  
 
67
If two threads use the same context then they need to synchronize in
68
68
order to be safe. In particular:
69
69
- when using talloc_enable_leak_report(), giving directly NULL as a  
70
70
parent context implicitly refers to a hidden "null context" global  
74
74
shouldn't be used by several threads simultaneously without  
75
75
synchronization.
76
76
 
 
77
talloc and shared objects
 
78
-------------------------
 
79
 
 
80
talloc can be used in shared objects. Special care needs to be taken
 
81
to never use talloc_autofree_context() in code that might be loaded
 
82
with dlopen() and unloaded with dlclose(), as talloc_autofree_context()
 
83
internally uses atexit(3). Some platforms like modern Linux handles
 
84
this fine, but for example FreeBSD does not deal well with dlopen()
 
85
and atexit() used simultaneously: dlclose() does not clean up the list
 
86
of atexit-handlers, so when the program exits the code that was
 
87
registered from within talloc_autofree_context() is gone, the program
 
88
crashes at exit.
 
89
 
77
90
 
78
91
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
79
92
(type *)talloc(const void *context, type);
117
130
talloc().
118
131
 
119
132
The return value of talloc_free() indicates success or failure, with 0
120
 
returned for success and -1 for failure. The only possible failure
121
 
condition is if the pointer had a destructor attached to it and the
122
 
destructor returned -1. See talloc_set_destructor() for details on
123
 
destructors.
124
 
 
125
 
If this pointer has an additional parent when talloc_free() is called
126
 
then the memory is not actually released, but instead the most
127
 
recently established parent is destroyed. See talloc_reference() for
128
 
details on establishing additional parents.
129
 
 
130
 
For more control on which parent is removed, see talloc_unlink()
131
 
 
132
 
talloc_free() operates recursively on its children.
133
 
 
134
 
From the 2.0 version of talloc, as a special case, talloc_free() is
135
 
refused on pointers that have more than one parent, as talloc would
136
 
have no way of knowing which parent should be removed. To free a
 
133
returned for success and -1 for failure. A possible failure condition
 
134
is if the pointer had a destructor attached to it and the destructor
 
135
returned -1. See talloc_set_destructor() for details on
 
136
destructors. Likewise, if "ptr" is NULL, then the function will make
 
137
no modifications and returns -1.
 
138
 
 
139
From version 2.0 and onwards, as a special case, talloc_free() is
 
140
refused on pointers that have more than one parent associated, as talloc
 
141
would have no way of knowing which parent should be removed. This is
 
142
different from older versions in the sense that always the reference to
 
143
the most recently established parent has been destroyed. Hence to free a
137
144
pointer that has more than one parent please use talloc_unlink().
138
145
 
139
146
To help you find problems in your code caused by this behaviour, if
148
155
talloc_set_log_stderr() for more information on talloc logging
149
156
functions.
150
157
 
 
158
talloc_free() operates recursively on its children.
 
159
 
151
160
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
152
 
int talloc_free_children(void *ptr);
 
161
void talloc_free_children(void *ptr);
153
162
 
154
163
The talloc_free_children() walks along the list of all children of a
155
164
talloc context and talloc_free()s only the children, not the context
156
165
itself.
157
166
 
 
167
A NULL argument is handled as no-op.
158
168
 
159
169
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
160
170
void *talloc_reference(const void *context, const void *ptr);
176
186
    will reduce the number of parents of this pointer by 1, and will
177
187
    cause this pointer to be freed if it runs out of parents.
178
188
 
179
 
  - you can talloc_free() the pointer itself. That will destroy the
180
 
    most recently established parent to the pointer and leave the
181
 
    pointer as a child of its current parent.
 
189
  - you can talloc_free() the pointer itself if it has at maximum one
 
190
    parent. This behaviour has been changed since the release of version
 
191
    2.0. Further informations in the description of "talloc_free".
182
192
 
183
193
For more control on which parent to remove, see talloc_unlink()
184
194
 
194
204
then this function will fail and will return -1.  Likewise, if "ptr"
195
205
is NULL, then the function will make no modifications and return -1.
196
206
 
197
 
Usually you can just use talloc_free() instead of talloc_unlink(), but
198
 
sometimes it is useful to have the additional control on which parent
199
 
is removed.
200
 
 
 
207
You can just use talloc_free() instead of talloc_unlink() if there
 
208
is at maximum one parent. This behaviour has been changed since the
 
209
release of version 2.0. Further informations in the description of
 
210
"talloc_free".
201
211
 
202
212
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
203
213
void talloc_set_destructor(const void *ptr, int (*destructor)(void *));
469
479
void talloc_report_full(const void *ptr, FILE *f);
470
480
 
471
481
This provides a more detailed report than talloc_report(). It will
472
 
recursively print the ensire tree of memory referenced by the
 
482
recursively print the entire tree of memory referenced by the
473
483
pointer. References in the tree are shown by giving the name of the
474
484
pointer that is referenced.
475
485
 
628
638
 
629
639
The talloc_asprintf_append() function appends the given formatted
630
640
string to the given string.
631
 
Use this varient when the string in the current talloc buffer may
 
641
Use this variant when the string in the current talloc buffer may
632
642
have been truncated in length.
633
643
 
634
644
This functions sets the name of the new pointer to the new
642
652
 
643
653
The talloc_asprintf_append() function appends the given formatted 
644
654
string to the end of the currently allocated talloc buffer.
645
 
Use this varient when the string in the current talloc buffer has
 
655
Use this variant when the string in the current talloc buffer has
646
656
not been changed.
647
657
 
648
658
This functions sets the name of the new pointer to the new
652
662
 
653
663
 
654
664
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
655
 
((type *)talloc_array(const void *ctx, type, uint_t count);
 
665
((type *)talloc_array(const void *ctx, type, unsigned int count);
656
666
 
657
667
The talloc_array() macro is equivalent to::
658
668
 
663
673
 
664
674
 
665
675
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
666
 
void *talloc_array_size(const void *ctx, size_t size, uint_t count);
 
676
void *talloc_array_size(const void *ctx, size_t size, unsigned int count);
667
677
 
668
678
The talloc_array_size() function is useful when the type is not
669
679
known. It operates in the same way as talloc_array(), but takes a size
670
680
instead of a type.
671
681
 
672
682
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
673
 
(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, uint_t count);
 
683
(typeof(ptr)) talloc_array_ptrtype(const void *ctx, ptr, unsigned int count);
674
684
 
675
685
The talloc_ptrtype() macro should be used when you have a pointer to an array
676
686
and want to allocate memory of an array to point at with this pointer. When compiling
716
726
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
717
727
talloc_set_type(const void *ptr, type);
718
728
 
719
 
This macro allows you to force the name of a pointer to be a
 
729
This macro allows you to force the name of a pointer to be of a
720
730
particular type. This can be used in conjunction with
721
731
talloc_get_type() to do type checking on void* pointers.
722
732
 
727
737
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
728
738
talloc_get_size(const void *ctx);
729
739
 
730
 
This function lets you know the amount of memory alloced so far by
 
740
This function lets you know the amount of memory allocated so far by
731
741
this context. It does NOT account for subcontext memory.
732
742
This can be used to calculate the size of an array.
733
743
 
754
764
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
755
765
void talloc_set_log_stderr(void)
756
766
 
757
 
This sets the talloc log function to write log messages to stderr
 
767
This sets the talloc log function to write log messages to stderr.