This file is indexed.

/usr/include/dbstl_utility.h is in libdb5.3-stl-dev 5.3.28-9+deb8u1.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
/*-
 * See the file LICENSE for redistribution information.
 *
 * Copyright (c) 2009, 2013 Oracle and/or its affiliates.  All rights reserved.
 *
 * $Id$
 */

#ifndef _DB_STL_UTILITY_H__
#define _DB_STL_UTILITY_H__

#include "dbstl_inner_utility.h"

START_NS(dbstl)

// This class allows users to configure dynamically how a specific type of 
// object is copied, stored, restored, and how to measure the type's
// instance size.
/** \defgroup dbstl_helper_classes dbstl helper classes
Classes of this module help to achieve various features of dbstl.
*/
/** \ingroup dbstl_helper_classes
@{
This class is used to register callbacks to manipulate an object of a 
complex type. These callbacks are used by dbstl at runtime  to 
manipulate the object.

A complex type is a type whose members are not located in a contiguous 
chunk of memory. For example, the following class A is a complex type 
because for any  instance a of class A, a.b_ points to another object 
of type B, and dbstl treats the  object that a.b_ points to as part of 
the data of the instance a. Hence, if the user needs to store a.b_ into 
a dbstl container, the user needs to register an appropriate callback to 
de-reference and store the object referenced by a.b. Similarly, the 
user also needs to register callbacks to marshall an array as well as 
to count the  number of elements in such an array.

class A { int m; B *p_; };
class B { int n; };

The user also needs to register callbacks for  
i). returning an object¡¯s size in bytes; 
ii). Marshalling and unmarshalling an object;
iii). Copying a complex object and  and assigning an object to another 
object of the same type; 
iv). Element comparison. 
v). Compare two sequences of any type of objects; Measuring the length 
of an object sequence and copy an object sequence.
 
Several elements  located in a contiguous chunk of memory form a sequence. 
An element of a sequence may be a simple object located at a contigous 
memory chunk, or a complex object, i.e. some of its members may contain 
references (pointers) to another region of memory. It is not necessary 
to store a special object to denote the end of the sequence.  The callback 
to traverse the constituent elements of the sequence needs to able to 
determine the end of the sequence.

Marshalling means packing the object's data members into a contiguous 
chunk of memory; unmarshalling is the opposite of marshalling. In other 
words, when you unmarshall an object, its data members are populated 
with values from a previously marshalled version of the object.

The callbacks need not be set to every type explicitly.  . dbstl will 
check if a needed callback function of this type is provided. 
If one is available, dbstl will use the registered callback.  If the 
appropriate callback is not provided, dbstl will use reasonable defaults 
to do the job.

For returning the size of an object,  the default behavior is to use the 
sizeof() operator;  For marshalling and unmarshalling, dbstl uses memcpy, 
so the default behavior is  sufficient for simple types whose data reside 
in a contiguous  chunk of memory; Dbstl uses  uses >, == and < for 
comparison operations; For char* and wchar_t * strings, dbstl already 
provides the appropriate callbacks, so you do not need to register them. 
In general, if the default behavior is adequate, you don't need to 
register the corresponding callback.

If you have registered proper callbacks, the DbstlElemTraits<T> can also be
used as the char_traits<T> class for std::basic_string<T, char_traits<T> >,
and you can enable your class T to form a basic_string<T, DbstlElemTraits<T>>,
and use basic_string's functionality and the algorithms to manipulate it.
*/
template <typename T>
class _exported DbstlElemTraits : public DbstlGlobalInnerObject
{
public:
	/// \name Callback_typedefs Function callback type definitions.
	/// Following are the callback function types, there is one function
	/// pointer data member for each of the type, and a pair of set/get
	/// functions for each function callback data member, and this is 
	/// the structure of this class.
	//@{
	/// Assign object src to object dest. Most often assignment callback 
	/// is not needed - the class copy constructor is sufficient.
	/// This description talks about the function of this type, rather 
	/// than the type itself, this is true to all the types in the group.
	typedef void (*ElemAssignFunct)(T& dest, const T&src);
	/// Read data from the chunk of memory pointed by srcdata, and assign
	/// to the object dest. This is also called unmashall.
	typedef void (*ElemRstoreFunct)(T& dest, const void *srcdata);
	/// Return object elem's size in bytes.
	typedef u_int32_t (*ElemSizeFunct)(const T& elem);
	/// Copy object elem's data to be persisted into a memory chunk 
	/// referenced by dest. The dest memory is large enough. 
	/// elem may not reside on a 
	/// consecutive chunk of memory. This is also called marshal.
	typedef void (*ElemCopyFunct)(void *dest, const T&elem);
	typedef int (*ElemCompareFunct)(const T&a, const T&b);
	/// Compares first num number of elements of sequence a and b, returns 
	/// negative/0/positive value if a is less/equal/greater than b.
	typedef int (*SequenceNCompareFunct)(const T *a, const T *b, 
	    size_t num);
	/// Compares sequence a and b, returns negative/0/positive
	/// value if a is less/equal/greater than b.
	typedef int (*SequenceCompareFunct)(const T *a, const T *b);
	/// Return the sequence's number of elements.
	typedef u_int32_t (*SequenceLenFunct)(const T *seqs);

	/// Copy the sequence seqs's first num elements to seqd.
	/// The sequence seqs of type T objects may not reside in a continuous
	/// chunk of memory, but the seqd sequence points to a consecutive 
	/// chunk of memory large enough to hold all objects from seqs.
	/// And if T is a complex type, you should register your ElemCopyFunct
	/// object marshalling manipulator
	typedef void (*SequenceCopyFunct)(T *seqd, const T *seqs, size_t num);
	//@}
	
	typedef T char_type;
	typedef long int_type;

	/// \name Interface compatible with std::string's char_traits.
	/// Following are char_traits funcitons, which make this class 
	/// char_traits compatiable, so that it can be used in 
	/// std::basic_string template, and be manipulated by the c++ stl 
	/// algorithms.
	//@{
	/// Assignone object to another.
	static void  assign(T& left, const T& right)
	{
		if (inst_->assign_)
			inst_->assign_(left, right);
		else
			left = right;
	}

	/// Check for equality of two objects.
	static bool  eq(const T& left, const T& right)
	{
		if (inst_->elemcmp_)
			return inst_->elemcmp_(left, right) == 0;
		else
			return left == right;
	}

	/// \brief Less than comparison.
	///
	/// Returns if object left is less than object right.
	static bool  lt(const T& left, const T& right)
	{
		if (inst_->elemcmp_)
			return inst_->elemcmp_(left, right) < 0;
		else 
			return left < right;
	}

	/// \brief Sequence comparison.
	///
	/// Compares the first cnt number of elements in the two 
	/// sequences seq1 and seq2, returns negative/0/positive if seq1 is
	/// less/equal/greater than seq2.
	static int  compare(const T *seq1, const T *seq2, size_t cnt)
	{
		if (inst_->seqncmp_)
			return inst_->seqncmp_(seq1, seq2, cnt);
		else {
			for (; 0 < cnt; --cnt, ++seq1, ++seq2)
				if (!eq(*seq1, *seq2))
					return (lt(*seq1, *seq2) ? -1 : +1);
		}
		return (0);
	}

	/// Returns the number of elements in sequence seq1. Note that seq1
	/// may or may not end with a trailing '\0', it is completely user's
	/// responsibility for this decision, though seq[0], seq[1],...
	/// seq[length - 1] are all sequence seq's memory.
	static size_t  length(const T *seq)
	{
		assert(inst_->seqlen_ != NULL);
		return (size_t)inst_->seqlen_(seq);
	}

	/// Copy first cnt number of elements from seq2 to seq1.
	static T * copy(T *seq1, const T *seq2, size_t cnt)
	{
		if (inst_->seqcpy_)
			inst_->seqcpy_(seq1, seq2, cnt);
		else {
			T *pnext = seq1;
			for (; 0 < cnt; --cnt, ++pnext, ++seq2)
				assign(*pnext, *seq2);
		}
		return (seq1);
	}

	/// Find within the first cnt elements of sequence seq the position 
	/// of element equal to elem.
	static const T * find(const T *seq, size_t cnt, const T& elem)
	{
		for (; 0 < cnt; --cnt, ++seq)
			if (eq(*seq, elem))
				return (seq);
		return (0);
	}

	/// \brief Sequence movement.
	///
	/// Move first cnt number of elements from seq2 to seq1, seq1 and seq2
	/// may or may not overlap.
	static T * move(T *seq1, const T *seq2, size_t cnt)
	{
		T *pnext = seq1;
		if (seq2 < pnext && pnext < seq2 + cnt)
			for (pnext += cnt, seq2 += cnt; 0 < cnt; --cnt)
				assign(*--pnext, *--seq2);
		else
			for (; 0 < cnt; --cnt, ++pnext, ++seq2)
				assign(*pnext, *seq2);
		return (seq1);
	}

	/// Assign first cnt number of elements of sequence seq with the 
	/// value of elem.
	static T * assign(T *seq, size_t cnt, T elem)
	{
		T *pnext = seq;
		for (; 0 < cnt; --cnt, ++pnext)
			assign(*pnext, elem);
		return (seq);
	}

	static T  to_char_type(const int_type& meta_elem)
	{	// convert metacharacter to character
		return ((T)meta_elem);
	}

	static int_type  to_int_type(const T& elem)
	{	// convert character to metacharacter
		return ((int_type)elem);
	}

	static bool  eq_int_type(const int_type& left,
		const int_type& right)
	{	// test for metacharacter equality
		return (left == right);
	}

	static int_type  eof()
	{	// return end-of-file metacharacter
		return ((int_type)EOF);
	}

	static int_type  not_eof(const int_type& meta_elem)
	{	// return anything but EOF
		return (meta_elem != eof() ? (int_type)meta_elem : 
		    (int_type)!eof());
	}

	//@}
	
	/// Factory method to create a singeleton instance of this class. 
	/// The created object will be deleted by dbstl upon process exit.
	inline static DbstlElemTraits *instance()
	{
		if (!inst_) {
			inst_ = new DbstlElemTraits();
			register_global_object(inst_);
		}
		return inst_;
	}

	/// \name Set/get functions for callback function pointers.
	/// These are the setters and getters for each callback function 
	/// pointers.
	//@{
	inline void set_restore_function(ElemRstoreFunct f)
	{
		restore_ = f;
	}

	inline ElemRstoreFunct get_restore_function() { return restore_; }

	inline void set_assign_function(ElemAssignFunct f)
	{
		assign_ = f;
	}

	inline ElemAssignFunct get_assign_function() { return assign_; }

	inline ElemSizeFunct get_size_function() { return size_; }

	inline void set_size_function(ElemSizeFunct f) { size_ = f; }

	inline ElemCopyFunct get_copy_function() { return copy_; }

	inline void set_copy_function(ElemCopyFunct f) { copy_ = f; }

	inline void set_sequence_len_function(SequenceLenFunct f)
	{
		seqlen_ = f;
	}

	inline SequenceLenFunct get_sequence_len_function() { return seqlen_; }

	inline SequenceCopyFunct get_sequence_copy_function()
	{
		return seqcpy_;
	}

	inline void set_sequence_copy_function(SequenceCopyFunct f)
	{
		seqcpy_ = f;
	}

	inline void set_compare_function(ElemCompareFunct f)
	{
		elemcmp_ = f;
	}

	inline ElemCompareFunct get_compare_function()
	{
		return elemcmp_;
	}

	inline void set_sequence_compare_function(SequenceCompareFunct f)
	{
		seqcmp_ = f;
	}

	inline SequenceCompareFunct get_sequence_compare_function()
	{
		return seqcmp_;
	}

	inline void set_sequence_n_compare_function(SequenceNCompareFunct f)
	{
		seqncmp_ = f;
	}

	inline SequenceNCompareFunct get_sequence_n_compare_function()
	{
		return seqncmp_;
	}
	//@}

	~DbstlElemTraits(){}
protected:
	inline DbstlElemTraits()
	{
		assign_ = NULL;
		restore_ = NULL;
		size_ = NULL;
		copy_ = NULL;
		seqlen_ = NULL;
		seqcpy_ = NULL;
		seqcmp_ = NULL;
		seqncmp_ = NULL;
		elemcmp_ = NULL;
	}

	static DbstlElemTraits *inst_;

	// Data members to hold registered function pointers.
	ElemAssignFunct assign_;
	ElemRstoreFunct restore_;
	ElemSizeFunct size_;
	ElemCopyFunct copy_;
	ElemCompareFunct elemcmp_;
	SequenceCompareFunct seqcmp_;
	SequenceNCompareFunct seqncmp_;
	SequenceLenFunct seqlen_;
	SequenceCopyFunct seqcpy_;
}; //DbstlElemTraits
//@} // dbstl_helper_classes

template<typename T>
DbstlElemTraits<T> *DbstlElemTraits<T>::inst_ = NULL;

/** 
\ingroup dbstl_helper_classes
@{
You can persist all bytes in a chunk of contiguous memory by constructing 
an DbstlDbt object A(use malloc to allocate the required number of bytes for 
A.data and copy the bytes to be stored into A.data, set other 
fields as necessary) and store A into a container, e.g. db_vector<DbstlDbt>, 
this stores the bytes rather than the object A into the underlying database.
The DbstlDbt class can help you avoid memory leaks, 
so it is strongly recommended that you use DbstlDbt rather than Dbt class.

DbstlDbt derives from Dbt class, and it does an deep copy on copy construction 
and assignment --by calling malloc to allocate its own memory and then 
copying the bytes to it; Conversely the destructor will free the memory on 
destruction if the data pointer is non-NULL. The destructor assumes the 
memory is allocated via malloc, hence why you are required to call 
malloc to allocate memory in order to use DbstlDbt. 

DbstlDbt simply inherits all methods from Dbt with no extra 
new methods except the constructors/destructor and assignment operator, so it 
is easy to use. 

In practice you rarely need to use DbstlDbt 
or Dbt because dbstl enables you to store any complex 
objects or primitive data. Only when you need to store raw bytes, 
e.g. a bitmap, do you need to use DbstlDbt. 

Hence, DbstlDbt is the right class to 
use to store any object into Berkeley DB via dbstl without memory leaks.

Don't free the memory referenced by DbstlDbt objects, it will be freed when the
DbstlDbt object is destructed.

Please refer to the two examples using DbstlDbt in 
TestAssoc::test_arbitrary_object_storage and
TestAssoc::test_char_star_string_storage member functions, 
which illustrate how to correctly use DbstlDbt in order to store raw bytes.

This class handles the task of allocating and de-allocating memory internally. 
Although it can be used to store data which cannot be handled by the 
DbstlElemTraits 
class, in practice, it is usually more convenient to register callbacks in the 
DbstlElemTraits class for the type you are storing/retrieving using dbstl.
*/
class DbstlDbt : public Dbt
{
	inline void deep_copy(const DbstlDbt &d)
	{
		u_int32_t len;
		if (d.get_data() != NULL && d.get_size() > 0) {
			if (d.get_flags() & DB_DBT_USERMEM)
				len = d.get_ulen();
			else
				len = d.get_size();

			set_data(DbstlMalloc(len));
			memcpy(get_data(), d.get_data(), len);
		}
	}

public:
	/// Construct an object with an existing chunk of memory of size1 
	/// bytes, refered by data1, 
	DbstlDbt(void *data1, u_int32_t size1) : Dbt(data1, size1){}
	DbstlDbt() : Dbt(){}
	/// The memory will be free'ed by the destructor.
	~DbstlDbt() 
	{ 
		free_mem();
	}

	/// This copy constructor does a deep copy.
	DbstlDbt(const DbstlDbt &d) : Dbt(d) 
	{
		deep_copy(d);
	}

	/// The memory will be reallocated if neccessary. 
	inline const DbstlDbt &operator = (const DbstlDbt &d)
	{
		ASSIGNMENT_PREDCOND(d)

		if (d.get_data() != NULL && d.get_size() > 0) {
			free_mem();
			memcpy(this, &d, sizeof(d));
		}

		deep_copy(d);
		return d;
	}

protected:
	/// Users don't need to call this function.
	inline void free_mem()
	{
		if (get_data()) {
			free(get_data());
			memset(this, 0, sizeof(*this));
		}
	}

};
//@} // dbstl_help_classes
END_NS

#endif // ! _DB_STL_UTILITY_H__