villa.3

harvest是一个下载html网页得机器人

.TH VILLA 3 "2003-11-27" "Man Page" "Quick Database Manager"

.SH NAME
Villa \- the advanced API of QDBM

.SH SYNOPSIS
.PP
.B #include <depot.h>
.br
.B #include <cabin.h>
.br
.B #include <villa.h>
.br
.B #include <stdlib.h>
.PP
.B typedef int(*VLCFUNC)(const char *aptr, int asiz, const char *bptr, int bsiz);
.PP
.B VILLA *vlopen(const char *name, int omode, VLCFUNC cmp);
.PP
.B int vlclose(VILLA *villa);
.PP
.B int vlput(VILLA *villa, const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode);
.PP
.B int vlout(VILLA *villa, const char *kbuf, int ksiz);
.PP
.B char *vlget(VILLA *villa, const char *kbuf, int ksiz, int *sp);
.PP
.B int vlvnum(VILLA *villa, const char *kbuf, int ksiz);
.PP
.B int vlputlist(VILLA *villa, const char *kbuf, int ksiz, CBLIST *vals);
.PP
.B int vloutlist(VILLA *villa, const char *kbuf, int ksiz);
.PP
.B CBLIST *vlgetlist(VILLA *villa, const char *kbuf, int ksiz);
.PP
.B int vlcurfirst(VILLA *villa);
.PP
.B int vlcurlast(VILLA *villa);
.PP
.B int vlcurprev(VILLA *villa);
.PP
.B int vlcurnext(VILLA *villa);
.PP
.B int vlcurjump(VILLA *villa, const char *kbuf, int ksiz, int jmode);
.PP
.B char *vlcurkey(VILLA *villa, int *sp);
.PP
.B char *vlcurval(VILLA *villa, int *sp);
.PP
.B void vlsettuning(VILLA *villa, int lrecmax, int nidxmax, int lcnum, int ncnum);
.PP
.B int vlsync(VILLA *villa);
.PP
.B int vloptimize(VILLA *villa);
.PP
.B char *vlname(VILLA *villa);
.PP
.B int vlfsiz(VILLA *villa);
.PP
.B int vllnum(VILLA *villa);
.PP
.B int vlnnum(VILLA *villa);
.PP
.B int vlrnum(VILLA *villa);
.PP
.B int vlwritable(VILLA *villa);
.PP
.B int vlfatalerror(VILLA *villa);
.PP
.B int vlinode(VILLA *villa);
.PP
.B int vltranbegin(VILLA *villa);
.PP
.B int vltrancommit(VILLA *villa);
.PP
.B int vltranabort(VILLA *villa);
.PP
.B int vlremove(const char *name);

.SH DESCRIPTION
.PP
Villa is the advanced API of QDBM.  It provides routines for managing a database file of B+ tree.  Each record is stored being sorted in order defined by a user.  As for hash databases, retrieving method is provided only as complete accord.  However, with Villa, it is possible to retrieve records specified by range.  Cursor is used in order to access each record in order.  It is possible to store records duplicating keys in a database.  Moreover, according to the transaction mechanism, you can commit or abort operations of a database in a lump.
.PP
Villa is implemented, based on Depot and Cabin.  A database file of Villa is actual one of Depot.  Although processing speed of retrieving and storing is slower than Depot, the size of a database is smaller.
.PP
In order to use Villa, you should include `depot.h', `cabin.h', `villa.h' and `stdlib.h' in the source files.  Usually, the following description will be near the beginning of a source file.
.PP
.RS
.B #include <depot.h>
.br
.B #include <cabin.h>
.br
.B #include <villa.h>
.br
.B #include <stdlib.h>
.RE
.PP
A pointer to `VILLA' is used as a database handle. It is like that some file I/O routines of `stdio.h' use a pointer to `FILE'.  A database handle is opened with the function `vlopen' and closed with `vlclose'.  You should not refer directly to any member of the handle.  If a fatal error occurs in a database, any access method via the handle except `vlclose' will not work and return error status.  Although a process is allowed to use multiple database handles at the same time, handles of the same database file should not be used.  Before the cursor is used, it should be initialized by one of `vlcurfirst', `vlcurlast' or `vlcurjump'.  Also after storing or deleting a record, the cursor should be initialized.
.PP
Villa also assign the external variable `dpecode' with the error code. The function `dperrmsg' is used in order to get the message of the error code.
.PP
You can define a comparing function to specify the order of records.  The function should be the following type.
.TP
.B typedef int(*VLCFUNC)(const char *aptr, int asiz, const char *bptr, int bsiz);
`aptr' specifies the pointer to the region of one key.  `asiz' specifies the size of the region of one key.  `bptr' specifies the pointer to the region of the other key.  `bsiz' specifies the size of the region of the other key.  The return value is positive if the former is big, negative if the latter is big, 0 if both are equivalent.
.PP
The function `vlopen' is used in order to get a database handle.
.TP
.B VILLA *vlopen(const char *name, int omode, VLCFUNC cmp);
`name' specifies the name of a database file.  `omode' specifies the connection mode: `VL_OWRITER' as a writer, `VL_OREADER' as a reader.  If the mode is `VL_OWRITER', the following may be added by bitwise or: `VL_OCREAT', which means it creates a new database if not exist, `VL_OTRUNC', which means it creates a new database regardless if one exists.  Both of `VL_OREADER' and `VL_OWRITER' can be added to by bitwise or: `VL_ONOLCK', which means it opens a database file without file locking.  `cmp' specifies the comparing function: `VL_CMPLEX' comparing keys in lexical order, `VL_CMPINT' comparing keys as objects of `int' in native byte order, `VL_CMPNUM' comparing keys as numbers of big endian, `VL_CMPDEC' comparing keys as decimal strings.  Any function based on the declaration of the type `VLCFUNC' can be assigned to the comparing function.  The comparing function should be kept same in the life of a database.  The return value is the database handle or `NULL' if it is not successful.  While connecting as a writer, an exclusive lock is invoked to the database file.  While connecting as a reader, a shared lock is invoked to the database file.  The thread blocks until the lock is achieved.  If `VL_ONOLCK' is used, the application is responsible for exclusion control.
.PP
The function `vlclose' is used in order to close a database handle.
.TP
.B int vlclose(VILLA *villa);
`villa' specifies a database handle.  If successful, the return value is true, else, it is false.  Because the region of a closed handle is released, it becomes impossible to use the handle.  Updating a database is assured to be written when the handle is closed.  If a writer opens a database but does not close it appropriately, the database will be broken.  If the transaction is activated and not committed, it is aborted.
.PP
The function `vlput' is used in order to store a record.
.TP
.B int vlput(VILLA *villa, const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode);
`villa' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `vbuf' specifies the pointer to the region of a value.  `vsiz' specifies the size of the region of the value.  If it is negative, the size is assigned with `strlen(vbuf)'.  `dmode' specifies behavior when the key overlaps, by the following values: `VL_DOVER', which means the specified value overwrites the existing one, `VL_DKEEP', which means the existing value is kept, `VL_DDUP', which means duplication of keys is allowed.  If successful, the return value is true, else, it is false.  A duplicated record is stored at the tail of the records of the same key.  The cursor becomes unavailable due to updating database.
.PP
The function `vlout' is used in order to delete a record.
.TP
.B int vlout(VILLA *villa, const char *kbuf, int ksiz);
`villa' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  If successful, the return value is true, else, it is false.  False is returned when no record corresponds to the specified key.  When the key of duplicated records is specified, the first record of the same key is deleted.  The cursor becomes unavailable due to updating database.
.PP
The function `vlget' is used in order to retrieve a record.
.TP
.B char *vlget(VILLA *villa, const char *kbuf, int ksiz, int *sp);
`villa' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `sp' specifies the pointer to a variable to which the size of the region of the return value is assigned.  If it is `NULL', it is not used.  If successful, the return value is the pointer to the region of the value of the corresponding record, else, it is `NULL'.  `NULL' is returned when no record corresponds to the specified key.  When the key of duplicated records is specified, the value of the first record of the same key is selected.  Because an additional zero code is appended at the end of the region of the return value, the return value can be treated as a character string.  Because the region of the return value is allocated with the `malloc' call, it should be released with the `free' call if it is no longer in use.
.PP
The function `vlvnum' is used in order to get the number of records corresponding a key.
.TP
.B int vlvnum(VILLA *villa, const char *kbuf, int ksiz);
`villa' specifies a database handle.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  The return value is the number of corresponding records.  If no record corresponds, 0 is returned.
.PP
The function `vlputlist' is used in order to store plural records corresponding a key.
.TP
.B int vlputlist(VILLA *villa, const char *kbuf, int ksiz, CBLIST *vals);
`villa' specifies a database handle connected as a writer.  `kbuf' specifies the pointer to the region of a key.  `ksiz' specifies the size of the region of the key.  If it is negative, the size is assigned with `strlen(kbuf)'.  `vals' specifies a list handle of values.  The list should not be empty.  If successful, the return value is true, else, it is false.  The cursor becomes unavailable due to updating database.