NDEX(1) 							       NDEX(1)



NAME
       ndex - binary search a text file database for character string(s)

SYNOPSIS
       ndex [-A] [-a] [-e] [-f] [-l] [-P] [-r m|n] [-v] dbfilename [string(s)]

DESCRIPTION
       Ndex  is for binary searching a text file database for character string
       keys. Any matches are printed to stdout, in order.

       The program requires mmap(2) to map the database file into the Unix  VM
       system. The database file name is a required command line argument.

       The database is a standard Unix text file, one record per line, in lex-
       ical order, constructed with "sort -u infile > outfile", or equivalent.

       The  database mechanism is conservative with machine resources, requir-
       ing about 12.5 micro-seconds of machine time to lookup a  word  in  the
       Unix  system  dictionary,  (the	dictionary  was  constructed using the
       paste(1) command to make a tab delimited  database  of  two  words  per
       record  that  was  5.0 MB in size, a quarter of a million records, on a
       single 466 MHz., Pentium, 128 MB of RAM,  lightly  loaded,  Linux  2.2,
       1024  byte  page size, using the time(1) command, divided by the number
       of words; likewise, to evaluate the database mechanism  in  a  "thrash"
       condition,  the	same tab delimited database was concatenated, 30 fold,
       to make a 150 MB database, consisting of  7.5  million  records,  which
       required 120 micro-seconds of machine time to look up each of the quar-
       ter million records.)

       Conceptually, the database mechanism is implemented similar to the  the
       technique used in the look(1) command.

       The  character  string keys to be searched for may be supplied as addi-
       tional optional command line arguments, or redirected  to  the  program
       via stdin, but not both.

       The  program  contains  less  than 200 lines of declarations and state-
       ments, all of which are documented with in line comments.

       The program has been compiled and tested on SunOS, Solaris, and	Linux,
       and may work on other brands of Unix.

       The  program  returns  0 if no error and any of the specified character
       string keys were found in the database file, 1 if no error and no char-
       acter  string keys were found; else returns a unique error code greater
       than 1 representing the error encountered-which will,  also,  print  an
       error diagnostic to stderr.

       The  -r	option	is useful for controlling the return value under error
       conditions-for example, the program return  can	be  preempted  if  the
       database  file  can  not  be  opened, (or read,) with a return value of
       match, or no match, depending on environmental requirements.

OPTIONS
       dbfilename
	      Database file name.

       string(s)
	      Character string key(s) to be searched for, (defaults to stdin).

       -A     Return  =  match	if  all  strings  found,  (match if any string
	      found).

       -a     Print all matches, (default prints first match).

       -e     Enable partial key search.

       -f     Lower case search, (the database must be lower case characters).

       -l     Print last match, (default prints first match).

       -P     Print the string(s) not in the database.

       -r m|n On file error, exit return = match for m, no match for n.

       -v     Print the program's version information.

WARNINGS
       Under buffer overflow conditions, the program makes no attempts at han-
       dling the situation-it just detects it, prints an  error  message,  and
       exits.

SEE ALSO
       look(1)

DIAGNOSTICS
       Error  messages for incompatible arguments, failure to allocate memory,
       inaccessible files, opening and closing files, and input record	buffer
       overflow.

AUTHORS
       ----------------------------------------------------------------------

       A license is hereby granted to reproduce this software source code and
       to create executable versions from this source code for personal,
       non-commercial use.  The copyright notice included with the software
       must be maintained in all copies produced.

       THIS PROGRAM IS PROVIDED "AS IS". THE AUTHOR PROVIDES NO WARRANTIES
       WHATSOEVER, EXPRESSED OR IMPLIED, INCLUDING WARRANTIES OF
       MERCHANTABILITY, TITLE, OR FITNESS FOR ANY PARTICULAR PURPOSE.  THE
       AUTHOR DOES NOT WARRANT THAT USE OF THIS PROGRAM DOES NOT INFRINGE THE
       INTELLECTUAL PROPERTY RIGHTS OF ANY THIRD PARTY IN ANY COUNTRY.

       Copyright (c) 2001-2007, John Conover, All Rights Reserved.

       Comments and/or bug reports should be addressed to:

	   john@email.johncon.com (John Conover)

       ----------------------------------------------------------------------



				January 1, 2007 		       NDEX(1)