Export (0) Print
Expand All
div
eof
Expand Minimize
This topic has not yet been rated - Rate this topic

bsearch_s 

Performs a binary search of a sorted array. This is version of bsearch with security enhancements as described in Security Enhancements in the CRT.


void *bsearch_s( 
   const void *key,
   const void *base,
   size_t num,
   size_t width,
   int ( __cdecl *compare ) ( void *, const void *, const void *),
   void * context
);

Parameters

key

Object to search for.

base

Pointer to base of search data.

num

Number of elements.

width

Width of elements.

compare

Callback function that compares two elements. The first argument is the context pointer. The second argument is a pointer to the key for the search. The third argument is a pointer to the array element to be compared with key.

context

A pointer to an object that can be accessed in the comparison function.

bsearch_s returns a pointer to an occurrence of key in the array pointed to by base. If key is not found, the function returns NULL. If the array is not in ascending sort order or contains duplicate records with identical keys, the result is unpredictable.

If invalid parameters are passed to the function, the invalid parameter handler is invoked as described in Parameter Validation. If execution is allowed to continue, errno is set to EINVAL and the function returns NULL. For more information, see errno, _doserrno, _sys_errlist, and _sys_nerr.

Error Conditions

key

base

compare

num

width

errno

NULL

any

any

any

any

EINVAL

any

NULL

any

!= 0

any

EINVAL

any

any

any

any

= 0

EINVAL

any

any

NULL

an

any

EINVAL

The bsearch_s function performs a binary search of a sorted array of num elements, each of width bytes in size. The base value is a pointer to the base of the array to be searched, and key is the value being sought. The compare parameter is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. bsearch_s calls the compare routine one or more times during the search, passing the context pointer and pointers to two array elements on each call. The compare routine compares the elements, and then returns one of the following values:

Value returned by compare routine Description

< 0

elem1 less than elem2

0

elem1 equal to elem2

> 0

elem1 greater than elem2

The context pointer may be useful if the searched data structure is part of an object, and the compare function needs to access members of the object. The compare function may cast the void pointer into the appropriate object type and access members of that object. The addition of the context parameter makes bsearch_s more secure since additional context may be used to avoid reentrancy bugs associated with using static variables to make data available to the compare function.

Routine Required header Compatibility

bsearch_s

<stdlib.h> and <search.h>

Windows 95, Windows 98, Windows 98 Second Edition, Windows Millennium Edition, Windows NT 4.0, Windows 2000, Windows XP Home Edition, Windows XP Professional, Windows Server 2003

For additional compatibility information, see Compatibility in the Introduction.

This program sorts a string array with qsort_s, and then uses bsearch_s to find the word "cat".

// crt_bsearch_s.cpp
// This program uses bsearch_s to search a string array,
// passing a locale as the context.
// compile with: /EHsc
#include <stdlib.h>
#include <stdio.h>
#include <search.h>
#include <process.h>
#include <locale.h>
#include <locale>
#include <windows.h>
using namespace std;

// The sort order is dependent on the code page.  Use 'chcp' at the
// command line to change the codepage.  When executing this application,
// the command prompt codepage must match the codepage used here:

#define CODEPAGE_850

#ifdef CODEPAGE_850
#define ENGLISH_LOCALE "English_US.850"
#endif

#ifdef CODEPAGE_1252
#define ENGLISH_LOCALE "English_US.1252"
#endif

// The context parameter lets you create a more generic compare.
// Without this parameter, you would have stored the locale in a
// static variable, thus making it vulnerable to thread conflicts
// (if this were a multithreaded program).

int compare( void *pvlocale, char **str1, char **str2)
{
    char *s1 = *str1;
    char *s2 = *str2;

    locale& loc = *( reinterpret_cast< locale * > ( pvlocale));

    return use_facet< collate<char> >(loc).compare(
       s1, s1+strlen(s1),
       s2, s2+strlen(s2) );
}

int main( void )
{
   char *arr[] = {"dog", "pig", "horse", "cat", "human", "rat", "cow", "goat"};

   char *key = "cat";
   char **result;
   int i;

   /* Sort using Quicksort algorithm: */
   qsort_s( arr,
            sizeof(arr)/sizeof(arr[0]),
            sizeof( char * ),
            (int (*)(void*, const void*, const void*))compare,
            &locale(ENGLISH_LOCALE) );

   for( i = 0; i < sizeof(arr)/sizeof(arr[0]); ++i )    /* Output sorted list */
      printf( "%s ", arr[i] );

   /* Find the word "cat" using a binary search algorithm: */
   result = (char **)bsearch_s( &key,
                                arr,
                                sizeof(arr)/sizeof(arr[0]),
                                sizeof( char * ),
                                (int (*)(void*, const void*, const void*))compare,
                                &locale(ENGLISH_LOCALE) );
   if( result )
      printf( "\n%s found at %Fp\n", *result, result );
   else
      printf( "\nCat not found!\n" );
}

Sample Output

cat cow dog goat horse human pig rat
cat found at 002F0F04

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.