NAME

ix − inverted index access functions

SYNOPSIS

#include <text/ix.h>

DESCRIPTION

These functions implement inverted indices.  They are part of the text library, libtext.  The link editor searches this library under the "-ltext" option.  Declarations for these functions may be obtained either from the include file <text/ix.h>, or from the master include file <text/text.h>.  For detailed information regarding the construction, use and maintenance of inverted indices using these functions, see the paper IndexingPaper in the directory /NextLibrary/Documentation/NeXT/RelNotes. 
 

SUMMARY

 
Index ∗ ixOpen(char ∗name, char ∗mode);

Opens the index in the .index subdirectory of directory name for reading if mode is "r"; opens the index for writing if mode is "w", creating the associated index structures, if necessary; or creates the index, destroying any preexisting index structures, if mode is "c".  Returns a pointer to an open index descriptor, or zero in the event of an error.  name may also describe the .index subdirectory or the main index file. 

void ixClose(Index ∗ix);

Closes ix, and frees the storage associated with it. 

void ixFlush(Index ∗ix);

Flushes buffered writes to the index structures associated with ix. 

Index ∗∗ ixOpenArray(char ∗∗path, char ∗mode);

For each directory name in the null-terminated path, attempts to open an index with the supplied mode.  Returns a list of open descriptors as a static, null-terminated array. 

ixCloseArray(Index ∗∗ixArray);

Closes ixArray, a null-terminated array of index descriptors returned by ixOpenArray. 

Index ∗ ixOpenParent(char ∗file);

Finds and opens the index that references file.  If file is an absolute path, backs up the tree along that path, looking for a .index file; otherwise starts from the current working directory.  Note that the first .index subdirectory encountered is assumed to be the index that references file.  No check is made to confirm or deny this assumption. 

int ixUnlink(char ∗file);

Removes the .index subdirectory and all of its contents from directory file.  file may also be the name of the .index subdirectory itsself, or even the name of the main index file. 

int _ixUnlink(char ∗file);

Removes the index structures from the .index subdirectory of directory file, but leaves the .index subdirectory and its other contents intact.  file may also be the name of the .index subdirectory itsself, or even the name of the main index file. 

char ∗ ixParentFolder(Index ∗ix);

Returns the name of the directory containing the .index subdirectory containing the index structures referred to by ix. 

char ∗ ixFullPath(Index ∗ix, char ∗file);

Returns the full pathname of file referenced by ix, by prepending the parent folder of ix to file if necessary. 

RefList ∗ ixGetRefList(Index ∗ix, char ∗expression, RefList ∗fl, ixSearchMethod searchBy, int (∗interrupt)());

Looks up expression in ix, and returns rl, or zero in the event of an error, or if expression was not found.  The number of references found is placed in rl, along with a list of pointers to References.  expression is a space separated list of one or more keywords.  The syntax is simple. The words AND, OR, and NOT in both upper and lower case are assumed to be boolean operators.  &, |, and ! may be used instead, as illustrated:

 word1 & word2 is equivalent to word1 AND word2
word1 | word2 is equivalent to word1 OR word2
word1 ! word2 is equivalent to word1 AND NOT word2
 

In the absence of an operator between adjacent words, and is assumed.  Grouping is not currently supported, and all three operators are left associative. 

void ixSortRefList(RefList ∗rl, ixSortMethod sortBy, ixSortDirection sortDirection);

Sorts rl, a RefList returned by ixGetRefList, according to the values of sortBy and sortDirection. 

void ixClearRefList(RefList ∗rl);

Empties rl, freeing the storage associated with it.  Note that to avoid memory leakage, this function must be called following a successful call to ixGetRefList before rl is reused, deallocated or released from scope. 

FileCell ∗ ixNewFileCell(void)

Creates and returns a pointer to a new FileCell, or zero if out of memory. 

ixFreeFileCell(FileCell ∗f);

Frees the storage associated with f. 

FileCell ∗ ixCopyFileCell(FileCell ∗f, char ∗file);

Returns a copy of f, using file, if it is supplied, as the name of the new FileCell. 

int ixWriteFileCell(Index ∗ix, FileCell ∗f);

Writes and registers f in index ix.  Returns zero in the event of an error.  Assigns a new id to f if f is new, or if the amount of index space required to write is greater than the amount of space already allocated to f in the index.  Two types of FileCells are supported. 
 
A standard FileCell contains a file name and other information describing the referenced file. Since standard FileCells are registered by file name, only one may reside in the index for a given file name. When a new standard FileCell is written, any existing standard FileCell with the same name is automatically removed from the index.
 
A pointer FileCell is a special FileCell that contains minimal information, and inherits whatever it lacks from the standard FileCell to which it points. A pointer FileCell associates additional information with a specific reference to a standard FileCell.  A pointer FileCell is denoted by a pointer field containing a valid standard FileCell pointer. Pointer FileCells are commonly used to associate aribtrary messages or regular expressions with a specific keyword references.

FileCell ∗_ixReadFileCell(int fd, ulong id);

Reads the FileCell at offset id in the file referred to by fd.  Returns zero in the event of an error. 

FileCell ∗ixReadFileCell(Index ∗ix, ulong id);

Reads the FileCell at offset id in the main index file of fd.  Returns zero in the event of an error, or if the referenced FileCell is marked for deletion. 

int ixWriteStatus(Index ∗ix, FileCell ∗f, char status);

Sets the status of in index ix to status.  A non-zero status indicates that the FileCell is marked for deletion.  Returns zero in the event of an error. 

FileCell ∗ ixInitFileCell(char ∗name, char ∗type, char ∗desc, char ∗message, char ∗regex, struct stat ∗b);

Allocates a new FileCell, and initializes it with the arguments supplied. 

int ixRemoveFileCell(Index ∗ix, FileCell ∗f, int remove);

Marks f for deletion from the index, and if remove is true, unlinks the file to which it refers from the filesystem.  Note that the space occupied by f will not be reclaimed until the index is reorganized by ixClean(1).  Returns zero in the event of an error. 

int ixRemoveFileCellById(Index ∗ix, ulong id, int remove);

Removes the FileCell referred to by id from the index, and if remove is true, unlinks the file to which refers from the filesystem.  Returns zero in the event of an error. 

int ixRemoveFileCellByName(Index ∗ix, char ∗name, int remove);

Removes the FileCell referred to by name from the index, and if remove is true, unlinks the file to which refers from the filesystem.  Returns zero in the event of an error. 

Registration ∗_ixGetRegistration(Index ∗ix, char ∗name);

Returns a pointer to the Registration associated with name, or zero if no registration was found for name. 

Registration ∗ixGetRegistration(Index ∗ix, char ∗name);

Returns a pointer to the Registration associated with name, or zero if no registration was found for name.  Unlike _ixGetRegistration, this function does not call dbError to complain if no registration is found for name. 

ulong ixGetRegistrationId(Index ∗ix, char ∗name);

Returns the id associated with name, or -1 if no registration was found for name. 

FileCell ∗ixGetRegistrationFileCell(Index ∗ix, char ∗name);

Returns the FileCell associated with name, or zero in the event of an error, or if no registration was found for name. 

ulong ixGetRegistrationDate(Index ∗ix, char ∗name);

Returns the registration date associated with name, or -1 if no registration was found for name. 

int ixPutRegistration(Index ∗ix, FileCell ∗f);

Registers fR in index ix.  Returns zero in the event of an error. 

int ixClearRegistrationByName(Index ∗ix, char ∗name);

Removes the registration associated with name from ix.  Returns zero in the event of an error. 

int ixClearRegistration(Index ∗ix, FileCell ∗f);

Removes the registration associated with f from ix.  Returns zero in the event of an error. 

ulong ixAddFileCell(Index ∗ix, NXStream ∗keys, FileCell ∗f);

Adds f to ix by calling ixWriteFileCell, and by adding associations to the keyword database for f with ixAssociate.  If keys is supplied, it must be a stream of white space separated word/weight pairs, as returned by pword(1).  If no description is supplied by f, the file name will be used as a default description.  If no type is supplied by f, filetype will be called with the file name and the stat buffer supplied by f.  If f does not contain a valid stat buffer, lstat(2) will be called with the file name supplied by f.  See fileutil(3) for more information on filetype.  Returns the id assigned to f by ixWriteFileCell, or zero in the event of an error. 
 
In addition to writing a standard FileCell, ixAddFileCell will write one pointer FileCell for each line supplied by keys that contains a third field following the word and weight fields.  A regular expression is assumed if the third field begins with slash; otherwise a message is assumed. 

int ixAssociated(Index ∗ix, char ∗s, ulong id);

True if s is associated with id. 

_ixAssociate(Index ∗ix, char ∗k, ulong id, float w);

Associates keyword k with id by adding id and the weight w to k’s reference list. 

ixAssociate(Index ∗ix, char ∗k, ulong id, float w);

Similar to _ixAssociate, but includes case-folding;

void ixPrintRefList(Index ∗ix, char ∗s, ixSearchMethod searchBy, ixSortMethod sortBy, ixSortDirection sortDirection);

Prints the references to s in ix, by calling ixGetRefList, ixSortRefList, and ixPrintFileCell. 

void ixPrintFileCell(FileCell ∗f, float weight);

Prints the contents of f on the standard output, using weight if it is supplied, or f->weight otherwise. 

int ixPrintFileCellById(Index ∗ix, ulong id, int pointerFlag);

Prints the contents of the FileCell referred to by id, by calling ixGetFileCellById and ixPrintFileCell.  Returns the size of the FileCell to facilitate looping over the contents of ix. 

SEE ALSO

text(3), db(3), fileutil(3), ixBuild(1)
/NextLibrary/Documentation/RelNotes/IndexingPaper

4th Berkeley Distribution  —  July 7, 1989