depot.3

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

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

.SH NAME
Depot \- the basic API of QDBM

.SH SYNOPSIS
.PP
.B #include <depot.h>
.br
.B #include <stdlib.h>
.PP
.B extern const char *dpversion;
.PP
.B extern int dpecode;
.PP
.B const char *dperrmsg(int ecode);
.PP
.B DEPOT *dpopen(const char *name, int omode, int bnum);
.PP
.B int dpclose(DEPOT *depot);
.PP
.B int dpput(DEPOT *depot, const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode);
.PP
.B int dpout(DEPOT *depot, const char *kbuf, int ksiz);
.PP
.B char *dpget(DEPOT *depot, const char *kbuf, int ksiz, int start, int max, int *sp);
.PP
.B int dpvsiz(DEPOT *depot, const char *kbuf, int ksiz);
.PP
.B int dpiterinit(DEPOT *depot);
.PP
.B char *dpiternext(DEPOT *depot, int *sp);
.PP
.B int dpsetalign(DEPOT *depot, int align);
.PP
.B int dpsync(DEPOT *depot);
.PP
.B int dpoptimize(DEPOT *depot, int bnum);
.PP
.B char *dpname(DEPOT *depot);
.PP
.B int dpfsiz(DEPOT *depot);
.PP
.B int dpbnum(DEPOT *depot);
.PP
.B int dpbusenum(DEPOT *depot);
.PP
.B int dprnum(DEPOT *depot);
.PP
.B int dpwritable(DEPOT *depot);
.PP
.B int dpfatalerror(DEPOT *depot);
.PP
.B int dpinode(DEPOT *depot);
.PP
.B int dpfdesc(DEPOT *depot);
.PP
.B int dpremove(const char *name);
.PP
.B int dpinnerhash(const char *kbuf, int ksiz);
.PP
.B int dpouterhash(const char *kbuf, int ksiz);
.PP
.B int dpprimenum(int num);

.SH DESCRIPTION
.PP
Depot is the basic API of QDBM.  Almost all features for managing a database provided by QDBM are implemented by Depot.  Other APIs are no more than wrappers of Depot.  Depot is the fastest in all APIs of QDBM.
.PP
In order to use Depot, you should include `depot.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 <stdlib.h>
.RE
.PP
A pointer to `DEPOT' 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 `dpopen' and closed with `dpclose'.  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 `dpclose' 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.
.PP
The external variable `dpversion' is the string containing the version information.
.TP
.B extern const char *dpversion;
.PP
The external variable `dpecode' is assigned with the last happened error code.  Refer to `depot.h' for details of the error codes.
.TP
.B extern int dpecode;
The initial value of this variable is `DP_NOERR'.  The other values are `DP_EFATAL', `DP_EMODE', `DP_EBROKEN', `DP_EKEEP', `DP_ENOITEM', `DP_EALLOC', `DP_EMAP', `DP_EOPEN', `DP_ECLOSE', `DP_ETRUNC', `DP_ESYNC', `DP_ESTAT', `DP_ESEEK', `DP_EREAD', `DP_EWRITE', `DP_ELOCK', `DP_EUNLINK', `DP_EMKDIR', `DP_ERMDIR', and `DP_EMISC'.
.PP
The function `dperrmsg' is used in order to get a message string corresponding to an error code.
.TP
.B const char *dperrmsg(int ecode);
`ecode' specifies an error code.  The return value is the message string of the error code.  The region of the return value is not writable.
.PP
The function `dpopen' is used in order to get a database handle.
.TP
.B DEPOT *dpopen(const char *name, int omode, int bnum);
`name' specifies the name of a database file.  `omode' specifies the connection mode: `DP_OWRITER' as a writer, `DP_OREADER' as a reader.  If the mode is `DP_OWRITER', the following may be added by bitwise or: `DP_OCREAT', which means it creates a new database if not exist, `DP_OTRUNC', which means it creates a new database regardless if one exists.  Both of `DP_OREADER' and `DP_OWRITER' can be added to by bitwise or: `DP_ONOLCK', which means it opens a database file without file locking.  `bnum' specifies the number of elements of the bucket array.  If it is not more than 0, the default value is specified.  The size of a bucket array is determined on creating, and can not be changed except for by optimization of the database.  Suggested size of a bucket array is about from 0.5 to 4 times of the number of all records to store.  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 `DP_ONOLCK' is used, the application is responsible for exclusion control.
.PP
The function `dpclose' is used in order to close a database handle.
.TP
.B int dpclose(DEPOT *depot);
`depot' 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.
.PP
The function `dpput' is used in order to store a record.
.TP
.B int dpput(DEPOT *depot, const char *kbuf, int ksiz, const char *vbuf, int vsiz, int dmode);
`depot' 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: `DP_DOVER', which means the specified value overwrites the existing one, `DP_DKEEP', which means the existing value is kept, `DP_DCAT', which means the specified value is concatenated at the end of the existing value.  If successful, the return value is true, else, it is false.
.PP
The function `dpout' is used in order to delete a record.
.TP
.B int dpout(DEPOT *depot, const char *kbuf, int ksiz);
`depot' 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.
.PP
The function `dpget' is used in order to retrieve a record.