1997-08-20 05:53:21 +02:00
|
|
|
@node Searching and Sorting, Pattern Matching, Message Translation, Top
|
1998-07-13 14:29:13 +02:00
|
|
|
@c %MENU% General searching and sorting functions
|
1996-12-08 09:01:13 +01:00
|
|
|
@chapter Searching and Sorting
|
1995-02-18 02:27:10 +01:00
|
|
|
|
|
|
|
This chapter describes functions for searching and sorting arrays of
|
|
|
|
arbitrary objects. You pass the appropriate comparison function to be
|
|
|
|
applied as an argument, along with the size of the objects in the array
|
|
|
|
and the total number of elements.
|
|
|
|
|
|
|
|
@menu
|
|
|
|
* Comparison Functions:: Defining how to compare two objects.
|
|
|
|
Since the sort and search facilities
|
|
|
|
are general, you have to specify the
|
1996-12-08 09:01:13 +01:00
|
|
|
ordering.
|
1995-02-18 02:27:10 +01:00
|
|
|
* Array Search Function:: The @code{bsearch} function.
|
|
|
|
* Array Sort Function:: The @code{qsort} function.
|
|
|
|
* Search/Sort Example:: An example program.
|
1997-09-21 03:47:02 +02:00
|
|
|
* Hash Search Function:: The @code{hsearch} function.
|
|
|
|
* Tree Search Function:: The @code{tsearch} function.
|
1995-02-18 02:27:10 +01:00
|
|
|
@end menu
|
|
|
|
|
1997-09-21 03:47:02 +02:00
|
|
|
@node Comparison Functions
|
1995-02-18 02:27:10 +01:00
|
|
|
@section Defining the Comparison Function
|
|
|
|
@cindex Comparison Function
|
|
|
|
|
|
|
|
In order to use the sorted array library functions, you have to describe
|
|
|
|
how to compare the elements of the array.
|
|
|
|
|
|
|
|
To do this, you supply a comparison function to compare two elements of
|
|
|
|
the array. The library will call this function, passing as arguments
|
|
|
|
pointers to two array elements to be compared. Your comparison function
|
|
|
|
should return a value the way @code{strcmp} (@pxref{String/Array
|
|
|
|
Comparison}) does: negative if the first argument is ``less'' than the
|
|
|
|
second, zero if they are ``equal'', and positive if the first argument
|
|
|
|
is ``greater''.
|
|
|
|
|
|
|
|
Here is an example of a comparison function which works with an array of
|
|
|
|
numbers of type @code{double}:
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
int
|
1999-01-08 09:54:53 +01:00
|
|
|
compare_doubles (const void *a, const void *b)
|
1995-02-18 02:27:10 +01:00
|
|
|
@{
|
1999-01-08 09:54:53 +01:00
|
|
|
const double *da = (const double *) a;
|
|
|
|
const double *db = (const double *) b;
|
|
|
|
|
|
|
|
return (*da > *db) - (*da < *db);
|
1995-02-18 02:27:10 +01:00
|
|
|
@}
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
The header file @file{stdlib.h} defines a name for the data type of
|
|
|
|
comparison functions. This type is a GNU extension.
|
|
|
|
|
|
|
|
@comment stdlib.h
|
|
|
|
@comment GNU
|
|
|
|
@tindex comparison_fn_t
|
|
|
|
@smallexample
|
|
|
|
int comparison_fn_t (const void *, const void *);
|
|
|
|
@end smallexample
|
|
|
|
|
1997-09-21 03:47:02 +02:00
|
|
|
@node Array Search Function
|
1995-02-18 02:27:10 +01:00
|
|
|
@section Array Search Function
|
|
|
|
@cindex search function (for arrays)
|
|
|
|
@cindex binary search function (for arrays)
|
|
|
|
@cindex array search function
|
|
|
|
|
1997-09-21 03:47:02 +02:00
|
|
|
Generally searching for a specific element in an array means that
|
|
|
|
potentially all elements must be checked. The GNU C library contains
|
|
|
|
functions to perform linear search. The prototypes for the following
|
|
|
|
two functions can be found in @file{search.h}.
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment SVID
|
|
|
|
@deftypefun {void *} lfind (const void *@var{key}, void *@var{base}, size_t *@var{nmemb}, size_t @var{size}, comparison_fn_t @var{compar})
|
|
|
|
The @code{lfind} function searches in the array with @code{*@var{nmemb}}
|
|
|
|
elements of @var{size} bytes pointed to by @var{base} for an element
|
|
|
|
which matches the one pointed to by @var{key}. The function pointed to
|
|
|
|
by @var{compar} is used decide whether two elements match.
|
|
|
|
|
|
|
|
The return value is a pointer to the matching element in the array
|
|
|
|
starting at @var{base} if it is found. If no matching element is
|
|
|
|
available @code{NULL} is returned.
|
|
|
|
|
|
|
|
The mean runtime of this function is @code{*@var{nmemb}}/2. This
|
2006-10-12 07:27:24 +02:00
|
|
|
function should only be used if elements often get added to or deleted from
|
1997-09-21 03:47:02 +02:00
|
|
|
the array in which case it might not be useful to sort the array before
|
|
|
|
searching.
|
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment SVID
|
|
|
|
@deftypefun {void *} lsearch (const void *@var{key}, void *@var{base}, size_t *@var{nmemb}, size_t @var{size}, comparison_fn_t @var{compar})
|
|
|
|
The @code{lsearch} function is similar to the @code{lfind} function. It
|
|
|
|
searches the given array for an element and returns it if found. The
|
|
|
|
difference is that if no matching element is found the @code{lsearch}
|
|
|
|
function adds the object pointed to by @var{key} (with a size of
|
|
|
|
@var{size} bytes) at the end of the array and it increments the value of
|
|
|
|
@code{*@var{nmemb}} to reflect this addition.
|
|
|
|
|
|
|
|
This means for the caller that if it is not sure that the array contains
|
|
|
|
the element one is searching for the memory allocated for the array
|
|
|
|
starting at @var{base} must have room for at least @var{size} more
|
|
|
|
bytes. If one is sure the element is in the array it is better to use
|
|
|
|
@code{lfind} so having more room in the array is always necessary when
|
|
|
|
calling @code{lsearch}.
|
|
|
|
@end deftypefun
|
|
|
|
|
1995-02-18 02:27:10 +01:00
|
|
|
To search a sorted array for an element matching the key, use the
|
|
|
|
@code{bsearch} function. The prototype for this function is in
|
|
|
|
the header file @file{stdlib.h}.
|
|
|
|
@pindex stdlib.h
|
|
|
|
|
|
|
|
@comment stdlib.h
|
1996-12-08 09:01:13 +01:00
|
|
|
@comment ISO
|
1995-02-18 02:27:10 +01:00
|
|
|
@deftypefun {void *} bsearch (const void *@var{key}, const void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare})
|
|
|
|
The @code{bsearch} function searches the sorted array @var{array} for an object
|
|
|
|
that is equivalent to @var{key}. The array contains @var{count} elements,
|
1996-12-08 09:01:13 +01:00
|
|
|
each of which is of size @var{size} bytes.
|
1995-02-18 02:27:10 +01:00
|
|
|
|
|
|
|
The @var{compare} function is used to perform the comparison. This
|
|
|
|
function is called with two pointer arguments and should return an
|
|
|
|
integer less than, equal to, or greater than zero corresponding to
|
|
|
|
whether its first argument is considered less than, equal to, or greater
|
|
|
|
than its second argument. The elements of the @var{array} must already
|
|
|
|
be sorted in ascending order according to this comparison function.
|
|
|
|
|
|
|
|
The return value is a pointer to the matching array element, or a null
|
|
|
|
pointer if no match is found. If the array contains more than one element
|
|
|
|
that matches, the one that is returned is unspecified.
|
|
|
|
|
|
|
|
This function derives its name from the fact that it is implemented
|
|
|
|
using the binary search algorithm.
|
|
|
|
@end deftypefun
|
|
|
|
|
1997-09-21 03:47:02 +02:00
|
|
|
@node Array Sort Function
|
1995-02-18 02:27:10 +01:00
|
|
|
@section Array Sort Function
|
|
|
|
@cindex sort function (for arrays)
|
|
|
|
@cindex quick sort function (for arrays)
|
|
|
|
@cindex array sort function
|
|
|
|
|
|
|
|
To sort an array using an arbitrary comparison function, use the
|
|
|
|
@code{qsort} function. The prototype for this function is in
|
|
|
|
@file{stdlib.h}.
|
|
|
|
@pindex stdlib.h
|
|
|
|
|
|
|
|
@comment stdlib.h
|
1996-12-08 09:01:13 +01:00
|
|
|
@comment ISO
|
1995-02-18 02:27:10 +01:00
|
|
|
@deftypefun void qsort (void *@var{array}, size_t @var{count}, size_t @var{size}, comparison_fn_t @var{compare})
|
|
|
|
The @var{qsort} function sorts the array @var{array}. The array contains
|
|
|
|
@var{count} elements, each of which is of size @var{size}.
|
|
|
|
|
|
|
|
The @var{compare} function is used to perform the comparison on the
|
|
|
|
array elements. This function is called with two pointer arguments and
|
|
|
|
should return an integer less than, equal to, or greater than zero
|
|
|
|
corresponding to whether its first argument is considered less than,
|
|
|
|
equal to, or greater than its second argument.
|
|
|
|
|
|
|
|
@cindex stable sorting
|
|
|
|
@strong{Warning:} If two objects compare as equal, their order after
|
|
|
|
sorting is unpredictable. That is to say, the sorting is not stable.
|
|
|
|
This can make a difference when the comparison considers only part of
|
|
|
|
the elements. Two elements with the same sort key may differ in other
|
|
|
|
respects.
|
|
|
|
|
|
|
|
If you want the effect of a stable sort, you can get this result by
|
|
|
|
writing the comparison function so that, lacking other reason
|
|
|
|
distinguish between two elements, it compares them by their addresses.
|
|
|
|
Note that doing this may make the sorting algorithm less efficient, so
|
|
|
|
do it only if necessary.
|
|
|
|
|
|
|
|
Here is a simple example of sorting an array of doubles in numerical
|
|
|
|
order, using the comparison function defined above (@pxref{Comparison
|
|
|
|
Functions}):
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
@{
|
|
|
|
double *array;
|
|
|
|
int size;
|
|
|
|
@dots{}
|
|
|
|
qsort (array, size, sizeof (double), compare_doubles);
|
|
|
|
@}
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
The @code{qsort} function derives its name from the fact that it was
|
|
|
|
originally implemented using the ``quick sort'' algorithm.
|
2000-05-23 08:37:29 +02:00
|
|
|
|
|
|
|
The implementation of @code{qsort} in this library might not be an
|
|
|
|
in-place sort and might thereby use an extra amount of memory to store
|
|
|
|
the array.
|
1995-02-18 02:27:10 +01:00
|
|
|
@end deftypefun
|
|
|
|
|
1997-09-21 03:47:02 +02:00
|
|
|
@node Search/Sort Example
|
1995-02-18 02:27:10 +01:00
|
|
|
@section Searching and Sorting Example
|
|
|
|
|
|
|
|
Here is an example showing the use of @code{qsort} and @code{bsearch}
|
|
|
|
with an array of structures. The objects in the array are sorted
|
|
|
|
by comparing their @code{name} fields with the @code{strcmp} function.
|
|
|
|
Then, we can look up individual objects based on their names.
|
|
|
|
|
|
|
|
@comment This example is dedicated to the memory of Jim Henson. RIP.
|
|
|
|
@smallexample
|
|
|
|
@include search.c.texi
|
|
|
|
@end smallexample
|
|
|
|
|
|
|
|
@cindex Kermit the frog
|
|
|
|
The output from this program looks like:
|
|
|
|
|
|
|
|
@smallexample
|
|
|
|
Kermit, the frog
|
|
|
|
Piggy, the pig
|
|
|
|
Gonzo, the whatever
|
|
|
|
Fozzie, the bear
|
|
|
|
Sam, the eagle
|
|
|
|
Robin, the frog
|
|
|
|
Animal, the animal
|
|
|
|
Camilla, the chicken
|
|
|
|
Sweetums, the monster
|
|
|
|
Dr. Strangepork, the pig
|
|
|
|
Link Hogthrob, the pig
|
|
|
|
Zoot, the human
|
|
|
|
Dr. Bunsen Honeydew, the human
|
|
|
|
Beaker, the human
|
|
|
|
Swedish Chef, the human
|
|
|
|
|
|
|
|
Animal, the animal
|
|
|
|
Beaker, the human
|
|
|
|
Camilla, the chicken
|
|
|
|
Dr. Bunsen Honeydew, the human
|
|
|
|
Dr. Strangepork, the pig
|
|
|
|
Fozzie, the bear
|
|
|
|
Gonzo, the whatever
|
|
|
|
Kermit, the frog
|
|
|
|
Link Hogthrob, the pig
|
|
|
|
Piggy, the pig
|
|
|
|
Robin, the frog
|
|
|
|
Sam, the eagle
|
|
|
|
Swedish Chef, the human
|
|
|
|
Sweetums, the monster
|
|
|
|
Zoot, the human
|
|
|
|
|
|
|
|
Kermit, the frog
|
|
|
|
Gonzo, the whatever
|
|
|
|
Couldn't find Janice.
|
|
|
|
@end smallexample
|
1997-09-21 03:47:02 +02:00
|
|
|
|
|
|
|
|
|
|
|
@node Hash Search Function
|
|
|
|
@section The @code{hsearch} function.
|
|
|
|
|
2006-10-12 07:27:24 +02:00
|
|
|
The functions mentioned so far in this chapter are for searching in a sorted
|
1997-09-21 03:47:02 +02:00
|
|
|
or unsorted array. There are other methods to organize information
|
|
|
|
which later should be searched. The costs of insert, delete and search
|
|
|
|
differ. One possible implementation is using hashing tables.
|
2006-10-12 07:27:24 +02:00
|
|
|
The following functions are declared in the header file @file{search.h}.
|
1997-09-21 03:47:02 +02:00
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment SVID
|
|
|
|
@deftypefun int hcreate (size_t @var{nel})
|
|
|
|
The @code{hcreate} function creates a hashing table which can contain at
|
|
|
|
least @var{nel} elements. There is no possibility to grow this table so
|
2006-10-12 07:27:24 +02:00
|
|
|
it is necessary to choose the value for @var{nel} wisely. The method
|
|
|
|
used to implement this function might make it necessary to make the
|
1997-09-21 03:47:02 +02:00
|
|
|
number of elements in the hashing table larger than the expected maximal
|
2006-10-12 07:27:24 +02:00
|
|
|
number of elements. Hashing tables usually work inefficiently if they are
|
1997-09-21 03:47:02 +02:00
|
|
|
filled 80% or more. The constant access time guaranteed by hashing can
|
|
|
|
only be achieved if few collisions exist. See Knuth's ``The Art of
|
|
|
|
Computer Programming, Part 3: Searching and Sorting'' for more
|
|
|
|
information.
|
|
|
|
|
|
|
|
The weakest aspect of this function is that there can be at most one
|
1997-10-15 07:34:02 +02:00
|
|
|
hashing table used through the whole program. The table is allocated
|
1997-09-21 03:47:02 +02:00
|
|
|
in local memory out of control of the programmer. As an extension the
|
|
|
|
GNU C library provides an additional set of functions with an reentrant
|
|
|
|
interface which provide a similar interface but which allow to keep
|
2000-02-22 10:00:35 +01:00
|
|
|
arbitrarily many hashing tables.
|
1997-09-21 03:47:02 +02:00
|
|
|
|
|
|
|
It is possible to use more than one hashing table in the program run if
|
|
|
|
the former table is first destroyed by a call to @code{hdestroy}.
|
|
|
|
|
|
|
|
The function returns a non-zero value if successful. If it return zero
|
|
|
|
something went wrong. This could either mean there is already a hashing
|
|
|
|
table in use or the program runs out of memory.
|
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment SVID
|
|
|
|
@deftypefun void hdestroy (void)
|
|
|
|
The @code{hdestroy} function can be used to free all the resources
|
|
|
|
allocated in a previous call of @code{hcreate}. After a call to this
|
|
|
|
function it is again possible to call @code{hcreate} and allocate a new
|
|
|
|
table with possibly different size.
|
|
|
|
|
|
|
|
It is important to remember that the elements contained in the hashing
|
|
|
|
table at the time @code{hdestroy} is called are @emph{not} freed by this
|
|
|
|
function. It is the responsibility of the program code to free those
|
1997-10-15 07:34:02 +02:00
|
|
|
strings (if necessary at all). Freeing all the element memory is not
|
1997-09-21 03:47:02 +02:00
|
|
|
possible without extra, separately kept information since there is no
|
|
|
|
function to iterate through all available elements in the hashing table.
|
|
|
|
If it is really necessary to free a table and all elements the
|
|
|
|
programmer has to keep a list of all table elements and before calling
|
|
|
|
@code{hdestroy} s/he has to free all element's data using this list.
|
1997-10-15 07:34:02 +02:00
|
|
|
This is a very unpleasant mechanism and it also shows that this kind of
|
1997-09-21 03:47:02 +02:00
|
|
|
hashing tables is mainly meant for tables which are created once and
|
|
|
|
used until the end of the program run.
|
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
Entries of the hashing table and keys for the search are defined using
|
|
|
|
this type:
|
|
|
|
|
|
|
|
@deftp {Data type} {struct ENTRY}
|
|
|
|
Both elements of this structure are pointers to zero-terminated strings.
|
|
|
|
This is a limiting restriction of the functionality of the
|
|
|
|
@code{hsearch} functions. They can only be used for data sets which use
|
|
|
|
the NUL character always and solely to terminate the records. It is not
|
|
|
|
possible to handle general binary data.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item char *key
|
|
|
|
Pointer to a zero-terminated string of characters describing the key for
|
|
|
|
the search or the element in the hashing table.
|
|
|
|
@item char *data
|
|
|
|
Pointer to a zero-terminated string of characters describing the data.
|
|
|
|
If the functions will be called only for searching an existing entry
|
|
|
|
this element might stay undefined since it is not used.
|
|
|
|
@end table
|
|
|
|
@end deftp
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment SVID
|
|
|
|
@deftypefun {ENTRY *} hsearch (ENTRY @var{item}, ACTION @var{action})
|
|
|
|
To search in a hashing table created using @code{hcreate} the
|
|
|
|
@code{hsearch} function must be used. This function can perform simple
|
|
|
|
search for an element (if @var{action} has the @code{FIND}) or it can
|
2002-01-29 09:58:51 +01:00
|
|
|
alternatively insert the key element into the hashing table. Entries
|
|
|
|
are never replaced.
|
1997-09-21 03:47:02 +02:00
|
|
|
|
|
|
|
The key is denoted by a pointer to an object of type @code{ENTRY}. For
|
|
|
|
locating the corresponding position in the hashing table only the
|
|
|
|
@code{key} element of the structure is used.
|
|
|
|
|
2002-01-29 09:58:51 +01:00
|
|
|
If an entry with matching key is found the @var{action} parameter is
|
|
|
|
irrelevant. The found entry is returned. If no matching entry is found
|
|
|
|
and the @var{action} parameter has the value @code{FIND} the function
|
|
|
|
returns a @code{NULL} pointer. If no entry is found and the
|
|
|
|
@var{action} parameter has the value @code{ENTER} a new entry is added
|
|
|
|
to the hashing table which is initialized with the parameter @var{item}.
|
|
|
|
A pointer to the newly added entry is returned.
|
1997-09-21 03:47:02 +02:00
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
As mentioned before the hashing table used by the functions described so
|
|
|
|
far is global and there can be at any time at most one hashing table in
|
|
|
|
the program. A solution is to use the following functions which are a
|
|
|
|
GNU extension. All have in common that they operate on a hashing table
|
|
|
|
which is described by the content of an object of the type @code{struct
|
|
|
|
hsearch_data}. This type should be treated as opaque, none of its
|
|
|
|
members should be changed directly.
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment GNU
|
|
|
|
@deftypefun int hcreate_r (size_t @var{nel}, struct hsearch_data *@var{htab})
|
1997-10-15 07:34:02 +02:00
|
|
|
The @code{hcreate_r} function initializes the object pointed to by
|
1997-09-21 03:47:02 +02:00
|
|
|
@var{htab} to contain a hashing table with at least @var{nel} elements.
|
|
|
|
So this function is equivalent to the @code{hcreate} function except
|
|
|
|
that the initialized data structure is controlled by the user.
|
|
|
|
|
2002-09-28 05:51:42 +02:00
|
|
|
This allows having more than one hashing table at one time. The memory
|
|
|
|
necessary for the @code{struct hsearch_data} object can be allocated
|
|
|
|
dynamically. It must be initialized with zero before calling this
|
|
|
|
function.
|
1997-09-21 03:47:02 +02:00
|
|
|
|
2006-11-10 22:12:47 +01:00
|
|
|
The return value is non-zero if the operation was successful. If the
|
|
|
|
return value is zero, something went wrong, which probably means the
|
|
|
|
programs ran out of memory.
|
1997-09-21 03:47:02 +02:00
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment GNU
|
|
|
|
@deftypefun void hdestroy_r (struct hsearch_data *@var{htab})
|
|
|
|
The @code{hdestroy_r} function frees all resources allocated by the
|
|
|
|
@code{hcreate_r} function for this very same object @var{htab}. As for
|
|
|
|
@code{hdestroy} it is the programs responsibility to free the strings
|
|
|
|
for the elements of the table.
|
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment GNU
|
|
|
|
@deftypefun int hsearch_r (ENTRY @var{item}, ACTION @var{action}, ENTRY **@var{retval}, struct hsearch_data *@var{htab})
|
|
|
|
The @code{hsearch_r} function is equivalent to @code{hsearch}. The
|
|
|
|
meaning of the first two arguments is identical. But instead of
|
1997-10-15 07:34:02 +02:00
|
|
|
operating on a single global hashing table the function works on the
|
1997-09-21 03:47:02 +02:00
|
|
|
table described by the object pointed to by @var{htab} (which is
|
|
|
|
initialized by a call to @code{hcreate_r}).
|
|
|
|
|
|
|
|
Another difference to @code{hcreate} is that the pointer to the found
|
|
|
|
entry in the table is not the return value of the functions. It is
|
|
|
|
returned by storing it in a pointer variables pointed to by the
|
|
|
|
@var{retval} parameter. The return value of the function is an integer
|
|
|
|
value indicating success if it is non-zero and failure if it is zero.
|
2000-02-22 10:00:35 +01:00
|
|
|
In the latter case the global variable @var{errno} signals the reason for
|
1997-09-21 03:47:02 +02:00
|
|
|
the failure.
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item ENOMEM
|
|
|
|
The table is filled and @code{hsearch_r} was called with an so far
|
|
|
|
unknown key and @var{action} set to @code{ENTER}.
|
|
|
|
@item ESRCH
|
|
|
|
The @var{action} parameter is @code{FIND} and no corresponding element
|
|
|
|
is found in the table.
|
|
|
|
@end table
|
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
|
|
|
|
@node Tree Search Function
|
|
|
|
@section The @code{tsearch} function.
|
|
|
|
|
|
|
|
Another common form to organize data for efficient search is to use
|
|
|
|
trees. The @code{tsearch} function family provides a nice interface to
|
|
|
|
functions to organize possibly large amounts of data by providing a mean
|
|
|
|
access time proportional to the logarithm of the number of elements.
|
|
|
|
The GNU C library implementation even guarantees that this bound is
|
|
|
|
never exceeded even for input data which cause problems for simple
|
|
|
|
binary tree implementations.
|
|
|
|
|
1997-10-15 07:34:02 +02:00
|
|
|
The functions described in the chapter are all described in the @w{System
|
1997-09-21 03:47:02 +02:00
|
|
|
V} and X/Open specifications and are therefore quite portable.
|
|
|
|
|
|
|
|
In contrast to the @code{hsearch} functions the @code{tsearch} functions
|
|
|
|
can be used with arbitrary data and not only zero-terminated strings.
|
|
|
|
|
|
|
|
The @code{tsearch} functions have the advantage that no function to
|
|
|
|
initialize data structures is necessary. A simple pointer of type
|
|
|
|
@code{void *} initialized to @code{NULL} is a valid tree and can be
|
* sysdeps/generic/bits/libc-tsd.h [USE___THREAD]: Conditional
changed from [USE_TLS && HAVE___THREAD].
* sysdeps/i386/dl-machine.h (elf_machine_type_class, elf_machine_rel):
Disable TLS relocs if [RTLD_BOOTSTRAP && !USE___THREAD].
* sysdeps/x86_64/dl-machine.h
(elf_machine_type_class, elf_machine_rela): Likewise.
* sysdeps/sh/dl-machine.h (elf_machine_type_class, elf_machine_rela):
Likewise.
* include/link.h (struct link_map): Remove member l_tls_tp_initialized.
* elf/rtld.c (_dl_start_final, dl_main): Don't use it.
(_dl_start): Conditionalize PT_TLS check on [USE___THREAD].
* sysdeps/i386/dl-tls.h (__TLS_GET_ADDR): Use ___tls_get_addr_internal
instead of ___tls_get_addr.
(___tls_get_addr_internal): Add attribute_hidden to decl.
* sysdeps/generic/ldsodefs.h (struct rtld_global): New variable
_dl_error_catch_tsd.
* elf/rtld.c (startup_error_tsd): New function.
(dl_main): Point _dl_error_catch_tsd at that.
* elf/dl-error.c: Don't use libc-tsd.h for DL_ERROR,
use new function pointer instead.
* elf/dl-tsd.c: New file.
* elf/Makefile (routines): Add it.
2002-10-07 Roland McGrath <roland@redhat.com>
* elf/dl-misc.c (_dl_debug_vdprintf): Use INTERNAL_SYSCALL macro for
writev if it's available. Otherwise if [RTLD_PRIVATE_ERRNO] then
take _dl_load_lock around calling __writev.
* sysdeps/unix/sysv/linux/i386/sysdep.h (INTERNAL_SYSCALL): New macro.
(INLINE_SYSCALL): Use that.
* sysdeps/generic/dl-sysdep.h: New file.
* sysdeps/mach/hurd/dl-sysdep.h: New file.
* sysdeps/generic/ldsodefs.h: Include <dl-sysdep.h>.
* include/errno.h [IS_IN_rtld]: Include <dl-sysdep.h> to define ...
[RTLD_PRIVATE_ERRNO]: Use a hidden global variable for errno and
access it directly.
* elf/dl-minimal.c (__errno_location): Removed.
* sysdeps/unix/i386/sysdep.S (__syscall_errno) [RTLD_PRIVATE_ERRNO]:
Use GOTOFF access for errno.
* sysdeps/unix/sysv/linux/i386/sysdep.h
[RTLD_PRIVATE_ERRNO] (SYSCALL_ERROR_HANDLER): Likewise.
* sysdeps/unix/x86_64/sysdep.S (__syscall_errno) [RTLD_PRIVATE_ERRNO]:
Use PC-relative access for errno.
* sysdeps/unix/sysv/linux/x86_64/sysdep.h
[RTLD_PRIVATE_ERRNO] (SYSCALL_ERROR_HANDLER): Likewise.
* include/tls.h: New file.
(USE___THREAD): New macro.
Define to 1 under [USE_TLS && HAVE___THREAD] and only when compiling
libc or libpthread.
* sysdeps/unix/sysv/linux/i386/sysdep.h [USE___THREAD]: Conditional
changed from [USE_TLS && HAVE___THREAD].
* sysdeps/unix/sysv/linux/x86_64/sysdep.h: Likewise.
* sysdeps/unix/i386/sysdep.S: Likewise.
* sysdeps/unix/x86_64/sysdep.S: Likewise.
* include/errno.h: Likewise.
* include/netdb.h: Likewise.
* include/resolv.h: Likewise.
* sysdeps/generic/errno.c: New file.
* csu/Makefile (aux): New variable, list errno.
* sysdeps/unix/sysv/linux/i386/sysdep.S (errno, _errno): Remove defns.
* sysdeps/unix/sysv/linux/m68k/sysdep.S: Likewise.
* sysdeps/unix/sysv/linux/x86_64/sysdep.S: Likewise.
* sysdeps/unix/sysv/linux/s390/s390-64/sysdep.S: Likewise.
* sysdeps/unix/sysv/linux/s390/s390-32/sysdep.S: Likewise.
* sysdeps/unix/sysv/linux/arm/sysdep.S: Likewise.
* sysdeps/unix/sysv/linux/cris/sysdep.S: Likewise.
* sysdeps/unix/sysv/linux/hppa/sysdep.c: Likewise.
* sysdeps/unix/sysv/linux/ia64/sysdep.S: Likewise.
* sysdeps/unix/sysv/linux/powerpc/sysdep.c: Likewise.
* sysdeps/unix/sysv/linux/sparc/sysdep.S: Likewise.
* sysdeps/unix/sysv/linux/sh/sysdep.S: Likewise.
* sysdeps/unix/alpha/sysdep.S: Likewise.
* sysdeps/generic/start.c: Likewise.
* sysdeps/unix/start.c: Likewise.
* sysdeps/unix/arm/start.c: Likewise.
* sysdeps/unix/bsd/ultrix4/mips/start.S: Likewise.
* sysdeps/unix/sparc/start.c: Likewise.
* sysdeps/unix/sysv/irix4/start.c: Likewise.
* sysdeps/unix/sysv/linux/mips/sysdep.S: File removed.
* manual/search.texi (Tree Search Function, Hash Search Function):
Mention search.h clearly.
2002-10-05 Roland McGrath <roland@redhat.com>
* elf/dl-fxstat64.c: File removed.
* elf/dl-xstat64.c: File removed.
* elf/Makefile (rtld-routines): Remove them.
* sysdeps/unix/sysv/linux/xstat64.c: Remove RTLD_STAT64 conditionals.
Instead, use strong_alias instead of versioned_symbol in the
!SHLIB_COMPAT case.
* sysdeps/unix/sysv/linux/fxstat64.c: Likewise.
* sysdeps/unix/sysv/linux/lxstat64.c: Likewise.
* include/shlib-compat.h
(SHLIB_COMPAT): Require that IS_IN_##lib be defined nonzero.
[! NOT_IN_libc] (IS_IN_libc): Define it.
* cppflags-iterator.mk (CPPFLAGS-$(cpp-src)): Use -Dx=1 not just -Dx.
* elf/Makefile (CPPFLAGS-.os): Likewise.
* sunrpc/rpc_main.c (main): Don't declare with noreturn attribute.
Return the status instead of calling exit.
* Makeconfig (CFLAGS): Prepend -std=gnu99.
* Makerules (+make-deps): Use $(CFLAGS) only for .c sources.
Remove superfluous rm command, whose @ plus make bugs hid
all these commands from the make output.
* include/stubs-prologue.h: New file. Give #error under #ifdef _LIBC.
* Makefile ($(inst_includedir)/gnu/stubs.h): Depend on it.
Use that file's contents instead of literal echo's for the prologue.
* include/features.h: Include <gnu/stubs.h> unconditionally.
* include/gnu/stubs.h: New file.
2002-09-30 Roland McGrath <roland@redhat.com>
* elf/rtld-Rules: New file.
* elf/Makefile ($(objpfx)librtld.map, $(objpfx)librtld.mk,
$(objpfx)rtld-libc.a): New targets.
(generated): Add them.
(reloc-link): Remove -o $@ from the variable.
($(objpfx)dl-allobjs.os): Add -o $@ after $(reloc-link).
(distribute): Add rtld-Rules.
(CPPFLAGS-.os): Define this instead of CFLAGS-.os.
* Makerules ($(+sysdir_pfx)sysd-rules): Emit rules for rtld-% targets.
(common-mostlyclean, common-clean): Clean up rtld-* files.
* sysdeps/unix/make-syscalls.sh: Add rtld-*.os target name to rules.
2002-10-11 12:52:20 +02:00
|
|
|
extended or searched. The prototypes for these functions can be found
|
|
|
|
in the header file @file{search.h}.
|
1997-09-21 03:47:02 +02:00
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment SVID
|
|
|
|
@deftypefun {void *} tsearch (const void *@var{key}, void **@var{rootp}, comparison_fn_t @var{compar})
|
|
|
|
The @code{tsearch} function searches in the tree pointed to by
|
|
|
|
@code{*@var{rootp}} for an element matching @var{key}. The function
|
1997-10-15 07:34:02 +02:00
|
|
|
pointed to by @var{compar} is used to determine whether two elements
|
1998-11-16 13:02:08 +01:00
|
|
|
match. @xref{Comparison Functions}, for a specification of the functions
|
1997-09-21 03:47:02 +02:00
|
|
|
which can be used for the @var{compar} parameter.
|
|
|
|
|
|
|
|
If the tree does not contain a matching entry the @var{key} value will
|
|
|
|
be added to the tree. @code{tsearch} does not make a copy of the object
|
|
|
|
pointed to by @var{key} (how could it since the size is unknown).
|
|
|
|
Instead it adds a reference to this object which means the object must
|
|
|
|
be available as long as the tree data structure is used.
|
|
|
|
|
|
|
|
The tree is represented by a pointer to a pointer since it is sometimes
|
|
|
|
necessary to change the root node of the tree. So it must not be
|
|
|
|
assumed that the variable pointed to by @var{rootp} has the same value
|
|
|
|
after the call. This also shows that it is not safe to call the
|
|
|
|
@code{tsearch} function more than once at the same time using the same
|
|
|
|
tree. It is no problem to run it more than once at a time on different
|
|
|
|
trees.
|
|
|
|
|
|
|
|
The return value is a pointer to the matching element in the tree. If a
|
|
|
|
new element was created the pointer points to the new data (which is in
|
|
|
|
fact @var{key}). If an entry had to be created and the program ran out
|
|
|
|
of space @code{NULL} is returned.
|
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment SVID
|
|
|
|
@deftypefun {void *} tfind (const void *@var{key}, void *const *@var{rootp}, comparison_fn_t @var{compar})
|
|
|
|
The @code{tfind} function is similar to the @code{tsearch} function. It
|
|
|
|
locates an element matching the one pointed to by @var{key} and returns
|
|
|
|
a pointer to this element. But if no matching element is available no
|
|
|
|
new element is entered (note that the @var{rootp} parameter points to a
|
|
|
|
constant pointer). Instead the function returns @code{NULL}.
|
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
Another advantage of the @code{tsearch} function in contrast to the
|
|
|
|
@code{hsearch} functions is that there is an easy way to remove
|
|
|
|
elements.
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment SVID
|
|
|
|
@deftypefun {void *} tdelete (const void *@var{key}, void **@var{rootp}, comparison_fn_t @var{compar})
|
|
|
|
To remove a specific element matching @var{key} from the tree
|
|
|
|
@code{tdelete} can be used. It locates the matching element using the
|
|
|
|
same method as @code{tfind}. The corresponding element is then removed
|
1999-11-10 03:42:49 +01:00
|
|
|
and a pointer to the parent of the deleted node is returned by the
|
|
|
|
function. If there is no matching entry in the tree nothing can be
|
|
|
|
deleted and the function returns @code{NULL}. If the root of the tree
|
|
|
|
is deleted @code{tdelete} returns some unspecified value not equal to
|
|
|
|
@code{NULL}.
|
1997-09-21 03:47:02 +02:00
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment GNU
|
|
|
|
@deftypefun void tdestroy (void *@var{vroot}, __free_fn_t @var{freefct})
|
|
|
|
If the complete search tree has to be removed one can use
|
|
|
|
@code{tdestroy}. It frees all resources allocated by the @code{tsearch}
|
|
|
|
function to generate the tree pointed to by @var{vroot}.
|
|
|
|
|
|
|
|
For the data in each tree node the function @var{freefct} is called.
|
|
|
|
The pointer to the data is passed as the argument to the function. If
|
|
|
|
no such work is necessary @var{freefct} must point to a function doing
|
|
|
|
nothing. It is called in any case.
|
|
|
|
|
|
|
|
This function is a GNU extension and not covered by the @w{System V} or
|
|
|
|
X/Open specifications.
|
|
|
|
@end deftypefun
|
|
|
|
|
|
|
|
In addition to the function to create and destroy the tree data
|
2000-03-10 09:41:39 +01:00
|
|
|
structure, there is another function which allows you to apply a
|
|
|
|
function to all elements of the tree. The function must have this type:
|
1997-09-21 03:47:02 +02:00
|
|
|
|
|
|
|
@smallexample
|
1998-12-17 21:59:54 +01:00
|
|
|
void __action_fn_t (const void *nodep, VISIT value, int level);
|
1997-09-21 03:47:02 +02:00
|
|
|
@end smallexample
|
|
|
|
|
1998-12-17 21:59:54 +01:00
|
|
|
The @var{nodep} is the data value of the current node (once given as the
|
1997-09-21 03:47:02 +02:00
|
|
|
@var{key} argument to @code{tsearch}). @var{level} is a numeric value
|
|
|
|
which corresponds to the depth of the current node in the tree. The
|
|
|
|
root node has the depth @math{0} and its children have a depth of
|
|
|
|
@math{1} and so on. The @code{VISIT} type is an enumeration type.
|
|
|
|
|
|
|
|
@deftp {Data Type} VISIT
|
|
|
|
The @code{VISIT} value indicates the status of the current node in the
|
|
|
|
tree and how the function is called. The status of a node is either
|
|
|
|
`leaf' or `internal node'. For each leaf node the function is called
|
|
|
|
exactly once, for each internal node it is called three times: before
|
|
|
|
the first child is processed, after the first child is processed and
|
1997-10-15 07:34:02 +02:00
|
|
|
after both children are processed. This makes it possible to handle all
|
1997-09-21 03:47:02 +02:00
|
|
|
three methods of tree traversal (or even a combination of them).
|
|
|
|
|
|
|
|
@table @code
|
|
|
|
@item preorder
|
|
|
|
The current node is an internal node and the function is called before
|
|
|
|
the first child was processed.
|
2000-10-30 05:18:33 +01:00
|
|
|
@item postorder
|
1997-09-21 03:47:02 +02:00
|
|
|
The current node is an internal node and the function is called after
|
|
|
|
the first child was processed.
|
2000-10-30 05:18:33 +01:00
|
|
|
@item endorder
|
1997-09-21 03:47:02 +02:00
|
|
|
The current node is an internal node and the function is called after
|
|
|
|
the second child was processed.
|
|
|
|
@item leaf
|
|
|
|
The current node is a leaf.
|
|
|
|
@end table
|
|
|
|
@end deftp
|
|
|
|
|
|
|
|
@comment search.h
|
|
|
|
@comment SVID
|
|
|
|
@deftypefun void twalk (const void *@var{root}, __action_fn_t @var{action})
|
2000-10-30 05:18:33 +01:00
|
|
|
For each node in the tree with a node pointed to by @var{root}, the
|
1997-09-21 03:47:02 +02:00
|
|
|
@code{twalk} function calls the function provided by the parameter
|
|
|
|
@var{action}. For leaf nodes the function is called exactly once with
|
|
|
|
@var{value} set to @code{leaf}. For internal nodes the function is
|
|
|
|
called three times, setting the @var{value} parameter or @var{action} to
|
|
|
|
the appropriate value. The @var{level} argument for the @var{action}
|
|
|
|
function is computed while descending the tree with increasing the value
|
1997-10-15 07:34:02 +02:00
|
|
|
by one for the descend to a child, starting with the value @math{0} for
|
1997-09-21 03:47:02 +02:00
|
|
|
the root node.
|
|
|
|
|
|
|
|
Since the functions used for the @var{action} parameter to @code{twalk}
|
2000-10-30 05:18:33 +01:00
|
|
|
must not modify the tree data, it is safe to run @code{twalk} in more
|
|
|
|
than one thread at the same time, working on the same tree. It is also
|
1997-09-21 03:47:02 +02:00
|
|
|
safe to call @code{tfind} in parallel. Functions which modify the tree
|
2001-05-21 19:38:30 +02:00
|
|
|
must not be used, otherwise the behavior is undefined.
|
1997-09-21 03:47:02 +02:00
|
|
|
@end deftypefun
|