### lfind - lsearch -- Find Key in Array

Format

>     #include <search.h>
>     char *lfind(char *search_key, char *base,
>                  unsigned int *num, unsigned int *width,
>                  int (*compare)(const void *key, const void *element));
>     char *lsearch(char *search_key, char *base,
>                    unsigned int *num, unsigned int *width,
>                    int (*compare)(const void *key, const void *element));

Language Level: XPG4, Extension
lfind and lsearch perform a linear search for the value search_key in an array of num elements, each of width bytes in size. The argument base points to the base of the array to be searched. If lsearch does not find the search_key, it adds the search_key to the end of the array and increments num by one. If lfind does not find the search_key, it does not add the search_key to the array.

Unlike bsearch, lsearch and lfind do not require that you sort the array first. The argument base points to the base of the array to be searched.

The compare argument is a pointer to a function you must supply that takes a pointer to the key argument and to an array element, in that order. Both lfind and lsearch call this function one or more times during the search. The function must compare the key and the element and return one of the following values:

Value | Meaning
Nonzero | key and element are different.
0 | key and element are identical.

Note: In earlier releases of the C/C++ run-time library, lfind and lsearch began with an underscore (_lfind and _lsearch). Because they are defined by the X/Open standard, the underscore has been removed. For compatibility, VisualAge C++ will map _lfind and _lsearch to lfind and lsearch for you.

Return Value
If search_key is found, both lsearch and lfind return a pointer to that element of the array to which base points. If search_key is not found, lsearch returns a pointer to a newly added item at the end of the array, while lfind returns NULL.

Example
This example uses lfind to search for the keyword PATH in the command-line arguments.

    #include <search.h>
    #include <string.h>
    #include <stdio.h>

    #define  NUM_FRUIT     10
    #define  ARRAY_SIZE    10

    /* Note: Library always calls functions internally with _Optlink              */
    /*       linkage convention.  Ensure that compare() is always                 */
    /*       _Optlink.                                                            */

    int _Optlink compare(const void *key, const void *element)
    {
       return (strncmp(*(char **)key, *(char **)element, strlen(*(char **)key)));
    }

    int main(int argc, char *argv[])
    {
       char **result;
       char *key;
       unsigned int num = 0, oldnum;
       int i;
       char *fruit[NUM_FRUIT] = { "apple", "pear", "tomato", "cherry", "banana",
                               "orange", "peach", "pear", "grape", "strawberry" };
       char *string[ARRAY_SIZE];

       if (argc != 2) {
          printf("Usage: %s string\n", argv[0]);
          return 1;
       }

       key = argv[1];

       /* Build the array. Note that "pear" appears twice in the input. */

       for (i=0; i<NUM_FRUIT && num<ARRAY_SIZE; ++i) {
          oldnum = num;
          result = (char **)lsearch((char *)&fruit[i], (char *)string, &num,
                    sizeof(char *), compare);
          if ( num==oldnum)
             printf("\"%s\" is already in the array\n", fruit[i]);
       }

       /* Find the array element that matches the command line argument */

       if ((result = (char **)lfind((char *)&key, (char *)string, &num,
                      sizeof(char *), compare)) != NULL)
          printf("\"%s\" was found\n", key);
       else
          printf("\"%s\" was not found\n", key);

       return 0;

       /************************************************************************
          For invocation: lfind peach
          The output should be:

          "pear" is already in the array
          "peach" was found
       ************************************************************************/
    }

bsearch -- Search Arrays
qsort -- Sort Array
<search.h>