NIS_DB

Section: C Library Functions (3)
Index
BSD mandoc

NAME

nis_db, db_initialize, db_create_table, db_destroy_table, db_first_entry,db_next_entry, db_reset_next_entry, db_list_entries, db_remove_entry,db_add_entry, db_table_exists, db_unload_table, db_checkpoint,db_standby, db_free_result - NIS+ database backend library functions

SYNOPSIS

Fd #include <rpcsvc/nis.h>Fd #include <rpcsvc/nis_db.h>Ft bool_tFn db_initialize const char *dictionary_pathnameFt db_statusFn db_create_table const char *table_name const table_obj *tableFt db_statusFn db_destroy_table const char *table_nameFt db_result *Fn db_first_entry const char *table_name const int numattrs const nis_attr *attrsFt db_result *Fn db_next_entry const char *table_name const db_next_desc *next_handleFt db_result *Fn db_reset_next_entry const char *table_name const db_next_desc *next_handleFt db_result *Fn db_list_entries const char *table_name const int numattrs const nis_attr *attrsFt db_result *Fn db_remove_entry const char *table_name const int numattrs const nis_attr *attrsFt db_result *Fn db_add_entry const char *table_name const int numattrs const nis_attr *attrs const entry_obj *entryFt db_statusFn db_table_exists const char *table_nameFt db_statusFn db_checkpoint const char *table_nameFt db_statusFn db_standby const char *table_nameFt voidFn db_free_result db_result *

DESCRIPTION

Thenis_dblibrary is used by theNIS+server,rpc.nisd8,to manipulate NIS+ tables. If provides functions that permit the creationand destruction of tables, as well as the addition and removal or entriesfrom tables.

UnlikeNIS v2 which uses a simple key/data metaphor for its maps,NIS+uses a relational model. Thenis_dbinterface is subset of a complete relational database system.Only those functions required by theNIS+server are provided.

The database supplied with the FreeBSD implementationof NIS+ uses theXDR File Format (XFF)for storing and managing its tables. XFF files are actually XDR datastreams that have been written to a file in a way that allows thevarious structures stored in the file to be retrieved in a ramdom accessfashion rather than sequentially. XFF is also log-based, which means thatchanges are first written to a log and then committed to the XFF filewhen the database is checkpointed.To speed up lookups, data which describesentries (and their relations to other entries) is kept in memory andmanaged using theRelation Cache Manager (RCM) The database is designed to optimize responsetime for retrievals in exchange for a small performance penalty forstorage and removal operations. This is considered to be a reasonabletradeoff sincerpc.nisd8spends far more time doing lookups than anything else. The library has beentested with tables containing up to 30,000 entries.

This library is not meant to be used by anyNIS+client utilities. AllNIS+clients that need to manipulate tables should instead use the functionsdescribed innis_tables3.The main reason for this restriction is that this library has nofacitlties for handling concurrent access to a single database bymultiple processes. This feature is provided instead by theNIS+server,rpc.nisd8.The underlying database functions may cache updates or removals inmemory, which makes it difficult to sychronize changes among multipleprocesses without resortingto complex inter-process communication or shared memory techniques.This problem is solved by using a singlerpc.nisd8as the database access server.

Thenis_dblibrary uses threeNIS+structures defined inAq Pa rpcsvc/nis.h .These aretable_obj entry_objandnis_attr Most functions return either adb_statuscode or a pointer to adb_resultstructure (which also contains adb_statuscode as one of its members).TheAq Pa rpcsvc/nis_db.hheader defines these structures as follows:

enum db_status = { DB_SUCCESS, DB_NOTFOUND, DB_NOTUNIQUE,                   DB_BADTABLE, DB_BADQUERY, DB_BADOBJECT,                   DB_MEMORY_LIMIT, DB_STORAGE_LIMIT,                   DB_INTERNAL_ERROR };struct db_result {        db_status       status;         /* Result status */        db_next_desc    nextinfo;       /* Next entry descriptor */        struct {                u_int           objects_len;                entry_obj       *objects_val;        } objects;                      /* A variable-sized array of                                           entry_obj structures. */        unsigned long   ticks;          /* execution time of};                                         function (in usecs) */

TheFt nis_attrstructure is defined inAq Pa rpcsvc/nis.has follows:

struct nis_attr        char    *zattr_ndx;             /* Name of index */        struct {                u_int   zattr_val_len;  /* Length of attribute */                char    *zattr_val_val; /* Attribute value */        } zattr_val;};

Descriptions of theFt entry_objandFt table objstructures can be found innis_objects3.

TheFt db_next_descstructure returned byFn db_first_entryorFn db_next_entryshould be treated by the caller as an opaque handle: it contains apointer to data that is internal to the library that should not bemodified. The caller can dispose of the handle using eitherFn db_reset_next_entryorFn db_free_result(the latter deallocates the entireFt db_resultstructure while the former clears only theFt db_next_descpointer and its associated resources).

TheFt objectsarray in theFt db_resultstructure will only contain objects if a called function returns aFt statusof DB_SUCCESS. EachFt db_resultstructure is dynamically allocated and must be freed withFn db_free_result .If there is insufficient memory available with which to createtheFt db_resultstructure, functions that normally returnFt db_resultwill instead return a NULL pointer.

Fn db_initializeis used to initialize the database. This function accepts a singleargument which is the name of a catalog file. The catalog fileis a small database which contains a list of all available tablesand their corresponding paths. It will be created if it does notalready exist. If it does exist and is valid, the database will readthe list of tables from the catalog and open each one, caching itsname anddb(3)handle for later use.Fn db_initializereturns TRUE on success and FALSE on failure.

Fn db_create_tablecreates the table named byFt table_namewith the attributes specified by the suppliedFt table_objstructure. It returns aFt db_statuscode of DB_SUCCESS if the table was successfully created, or someother code indicating an error if the table creation failed.

Fn db_destroy_tabledestroys the table specified by theFt table_nameargument. All open handles related to the table are closed andits entry is removed from the library's internal cache. LikeFn db_create_table ,it returns aFt db_statuscode to indicate success or failure.

Fn db_first_entryreturns a copy of the first entry in the specified table that matchesthe specified attributes.Ft attrsis an array ofFt nis_attrstructures containingFt numattrsmembers. If no attributes are specified, the first entry in thetable is returned. If the specified attributes don't match anyentries in the table, the query fails and DB_NOTFOUND is returned.If the query is successful, theFt nextinfostructure inFt db_resultwill contain an opaque handle that can be used as theFt next_handleargument toFn db_next_entryorFn db_reset_next_entry .The behavior ofFn db_first_entryvaries somewhat depending on the specified arguments:

If the user specifies no attributes,Fn db_first_entryreturns the very first entry in the table and setsFt nextinfoto point to the second entry. Subsequent calls toFn db_next_entrycan then be used to enumerate the entire contents of a table.
If the user specifies attributes that don't match any entryin the table,Fn db_first_entryreturns DB_NOTFOUND.
If the user specifies arguments that match exactly one entry inthe table,Fn db_first_entryreturns that entry and setsFt nextinfoto point to the entry immediately following it. Subsequent callstoFn db_next_entrycan then be used to enumerate the contents of the table startingfrom the matched entry (as opposed to starting right from thebeginning).
If the user specifies attributes that match more than one entry,Fn db_first_entryreturns the first matching entry and setsFt nextinfoto point to the next matching entry. Subsequent calls toFt db_next_entrycan then be used to enumerate the list of matching entries.

The latter behavior is equivalent to usingFn db_list_entriesexcept that the entries are retrieved from the table one at a timerather than all at once. TheFt db_resultstructure returned byFn db_first_entrycan be freed withFn db_free_result .

Fn db_next_entryreturns a copy of the next entry in the specified table as indicatedby theFt next_handlestructure. A call toFn db_first_entryfollowed by successive calls toFn db_next_entrycan be used to enumerate the entire contents of a table or justthose entries that match the attributes supplied toFn db_first_entry .LikeFn db_first_entry ,this function returns aFt nextinfostructure pointing to the next entry in the query. When the lastmatching entry has been reached, the returned structure will be empty.It is therefore not necessary to callFn db_reset_next_entryonce the end of the list has been reached.The returnedFt db_resultstructure can be freed withFn db_free_result .

Fn db_reset_next_entryis used to terminate aFn db_first_entry/Fn db_next_entryquery before reaching the end of the list. Once aFt next_handlehas been destroyed usingFn db_reset_next_entry ,subsequent attempts to use the handle withFn db_next_entrywill return DB_BADQUERY. TheFt db_resultstructure which contained theFt db_next_descstructure that was destroyed can subsequently be freed withFt db_free_result .

Fn db_list_entriesretrieves copies of entries that match the specified attributes.If no entries match, it returns DB_NOTFOUND.Ft attrsis an attay ofFt nis_attrstructures containingFt numattrsmembers. ThFt db_resultstructure returned byFn db_first_entrycan be freed withFn db_free_result .

Fn db_remove_entryremoves entries that match the specified attributes from thespecified table. The returnedFt db_resultstructure can be freed withFn db_free_result .Ft attrsis an array ofFt nis_attrsstructures withFt numattrsmembers.

Fn db_add_entryadds a copy of the specified entry to the table specified byFt table_name .This function can also be used to replace entries: if the callerspecifies a set of attributes that match an existing entry in thetable, this entry will be removed and replaced with the new one.The specified attributes must match only one entry in the table: ifmore than one matching entry is found, a DB_NOTUNIQUE status isreturned. If no entries match the specified attributes, the newentry is simply added. Note that this means that to add an entry,at least one attribute must be supplied even if it does not matchanything: if no attributes are specified (Ft numattrsis zero),Fn db_add_entryreturns DB_BADQUERY. Note that it is possible to add the exactsame entry twice: the library does permit duplicate entries.

Fn db_table_existsprovides an efficient method for determining whether or not thenamed table exists. This function can be used to quickly confirmthe existence of a given table prior to making an actual query.

Fn db_unload_tableis used to remove the specified table from the library's internalqueue. This process deallocates the table's queue entry, flushesthe table's RCM resources and closes all its file descriptors. TheNIS+server,rpc.nisd8,monitors table access patterns and uses this function to deactivatetables that have not been used in a while, thus conserving systemresources. It is not necessary to reload a table once it has beenunloaded: any subsequent queries involving the specified table willcause the table to automatically be reopened and loaded back intothe internal queue.

Fn db_checkpoint ,in the context of this particular library implementation, causesall log entries to be merged with the main XFF table file. Normally,any changes to a table are first written to a log; the table fileitself remains untouched. In the event of a crash, the library willimage of the table back up to date. Corrupted or incomplete log entriesare rejected. In this way, the table data is always maintained ina consistent state. In database parlance,Fn db_checkpointis used to 'commit' the changes described in the log to the maintable file. Once the log has been rolled forward, it is removed.When a table has been checkpointed, the table handle itself remains openand is retained in the library's internal queue.

Fn db_free_resultfrees any resources allocated by any of thenis_dbfunctions that return a pointer to aFt db_resultstructure. If theFt db_resultstructure in question also containsFt nextinfostructure,Fn db_free_resultwill callFn db_reset_next_entryto deallocate it.

Fn db_standbycauses the file descriptors of the specified table to be closed.This has the additional effect of causing the underlying databaseroutines to free up resources allocated to the database handle.The internal queue entry for the table remains in memory. Subsequentqueries involving the specified table will cause it to automaticallybe reopened.

RETURN VALUES

The functionsFn db_add_entry ,Fn db_first_entry ,Fn db_next_entry ,Fn db_list_entriesandFn db_remove_entryreturn a pointer to aFt db_resultstructure, unless there is not enough memory available to allocatesuch a structure, in which case they will return NULL. This structurewill always contain at least a status code and may also contain anarray of objects and/or a pointer to aFt nextinfohandle.

TheFn db_create_table ,Fn db_destroy_table ,Fn db_unload_table ,Fn db_standbyandFn db_checkpointfunctions return only aFt db_status code. This code is effectively nothing more than asigned integer.

Fn db_free_resultreturns nothing.

ERRORS

The functions in thenis_dblibrary may return any of the following status codes:

Bq Er DB_SUCCESS: The query or operation completed successfully.
Bq Er DB_NOTFOUND: The specified name or entry was not found.
Bq Er DB_NOTUNIQUE: An attempt was made to remove an entry from a table that was notuniquely specified.
Bq Er DB_BADQUERY: The query submitted to the database was invalid (i.e. nonexistentfields were specified, an invalid table was specified, the attributesarray was invalid or corrupt).
Bq Er DB_BADTABLE: The table was corrupted.
Bq Er DB_BADOBJECT: The fields of the specified entry do not conform to the fieldsof the table to which it is being added.
Bq Er DB_MEMORY_LIMIT: The database was unable to complete the requested operation dueto a lack of available memory.
Bq Er DB_STORAGE_LIMIT: The database was unable to complete the requested operation dueto a lack of disk space.
Bq Er DB_INTERNAL_ERROR: The database was unable to complete the requested operation dueto some internal error (either a programming error or anunrecoverable exception).

STANDARDS

There are no standards with respect to NIS+. Sun is making everythingup as they go.

COMPATIBILITY

This implementation of thenis_dblibrary meets the specifications described in the Solaris 2.5.1nis_db3nmanual page however it has not been tested as a direct replacemntfor libnisdb.so on a Solaris system.

When asked to destroy a table that does not exist, the Solarisversion ofFn db_destroy_tablereturns a db_status code of 9. This value is not defined anywherein theNIS+headers and its meaning is therefore unknown. This implementationof the library returns DB_BADTABLE instead.

BUGS

Deleting entries from committed XFF table files is something of anarduous task. RCM indexes entries in terms of their offset withinan XFF file (in other words, RCM indexes are really seek pointers).If an entry is deleted and the XFF file compacted to reclaim theunused space, all the seek pointers that refer to entriesafter the deleted one must be fixed up to account for the deletion.While this is not hard to accomplish, it requires traversing allof the RCM indexes in order to find those which need to be updated.

HISTORY

This implementation of thenis_dblibrary was written for and is scheduled to appear in a futurerelease of FreeBSD 2.x as part of a complete, freely availableNIS+ client and server package. This library was written entirelyfrom scratch: no Sun code other than thepublically available NIS+ header files was referenced.

AUTHOR

Bill Paul <wpaulAATTctr.columbia.edu>

This document was created byman2html,using the manual pages.