xref: /dragonfly/lib/libc/db/man/dbm.3 (revision 0bb9290e) 
1.\" Copyright (c) 1999 Tim Singletary
2.\" No copyright is claimed.
3.\"
4.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
5.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
6.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
7.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
8.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
9.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
10.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
11.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
12.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
13.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
14.\" SUCH DAMAGE.
15.\"
16.\" $FreeBSD: src/lib/libc/db/man/dbm.3,v 1.2.2.5 2003/03/15 15:11:05 trhodes Exp $
17.\" $DragonFly: src/lib/libc/db/man/dbm.3,v 1.3 2006/05/26 19:39:36 swildner Exp $
18.\"
19.\" Note: The date here should be updated whenever a non-trivial
20.\" change is made to the manual page.
21.Dd July 7, 1999
22.Dt DBM 3
23.Os
24.Sh NAME
25.Nm dbm_clearerr ,
26.Nm dbm_close ,
27.Nm dbm_delete ,
28.Nm dbm_dirfno ,
29.Nm dbm_error ,
30.Nm dbm_fetch ,
31.Nm dbm_firstkey ,
32.Nm dbm_nextkey ,
33.Nm dbm_open ,
34.Nm dbm_store
35.Nd database access functions
36.Sh SYNOPSIS
37.In fcntl.h
38.In ndbm.h
39.Ft DBM *
40.Fn dbm_open "const char *base" "int flags" "int mode"
41.Ft void
42.Fn dbm_close "DBM *db"
43.Ft int
44.Fn dbm_store "DBM *db" "datum key" "datum data" "int flags"
45.Ft datum
46.Fn dbm_fetch "DBM *db" "datum key"
47.Ft int
48.Fn dbm_delete "DBM *db" "datum key"
49.Ft datum
50.Fn dbm_firstkey "DBM *db"
51.Ft datum
52.Fn dbm_nextkey "DBM *db"
53.Ft int
54.Fn dbm_error "DBM *db"
55.Ft int
56.Fn dbm_clearerr "DBM *db"
57.Ft int
58.Fn dbm_dirfno "DBM *db"
59.Sh DESCRIPTION
60Database access functions.
61These functions are implemented using
62.Xr dbopen 3
63with a
64.Xr hash 3
65database.
66.Pp
67.Vt datum
68is declared in
69.In ndbm.h :
70.Bd -literal
71typedef struct {
72	char *dptr;
73	int dsize;
74} datum;
75.Ed
76.Pp
77The
78.Fn dbm_open base flags mode
79function
80opens or creates a database.
81The
82.Fa base
83argument
84is the basename of the file containing
85the database; the actual database has a
86.Pa .db
87suffix.
88I.e., if
89.Fa base
90is
91.Qq Li /home/me/mystuff
92then the actual database is in the file
93.Pa /home/me/mystuff.db .
94The
95.Fa flags
96and
97.Fa mode
98arguments
99are passed to
100.Xr open 2 .
101.Pq Dv O_RDWR | O_CREAT
102is a typical value for
103.Fa flags ;
104.Li 0660
105is a typical value for
106.Fa mode .
107.Dv O_WRONLY
108is not allowed in
109.Fa flags .
110The pointer returned by
111.Fn dbm_open
112identifies the database and is the
113.Fa db
114argument to the other functions.
115The
116.Fn dbm_open
117function
118returns
119.Dv NULL
120and sets
121.Va errno
122if there were any errors.
123.Pp
124The
125.Fn dbm_close db
126function
127closes the database.
128The
129.Fn dbm_close
130function
131normally returns zero.
132.Pp
133The
134.Fn dbm_store db key data flags
135function
136inserts or replaces an entry in the database.
137The
138.Fa flags
139argument
140is either
141.Dv DBM_INSERT
142or
143.Dv DBM_REPLACE .
144If
145.Fa flags
146is
147.Dv DBM_INSERT
148and the database already contains an entry for
149.Fa key ,
150that entry is not replaced.
151Otherwise the entry is replaced or inserted.
152The
153.Fn dbm_store
154function
155normally returns zero but returns 1 if the entry could not be
156inserted (because
157.Fa flags
158is
159.Dv DBM_INSERT ,
160and an entry with
161.Fa key
162already exists) or returns -1 and sets
163.Va errno
164if there were any errors.
165.Pp
166The
167.Fn dbm_fetch db key
168function
169returns
170.Dv NULL
171or the
172.Fa data
173corresponding to
174.Fa key .
175.Pp
176The
177.Fn dbm_delete db key
178function
179deletes the entry for
180.Fa key .
181The
182.Fn dbm_delete
183function
184normally returns zero but returns 1 if there was no entry with
185.Fa key
186in the database or returns -1 and sets
187.Va errno
188if there were any errors.
189.Pp
190The
191.Fn dbm_firstkey db
192function
193returns the first key in the database.
194The
195.Fn dbm_nextkey db
196function
197returns subsequent keys.
198The
199.Fn db_firstkey
200function
201must be called before
202.Fn dbm_nextkey .
203The order in which keys are returned is unspecified and may appear
204random.
205The
206.Fn dbm_nextkey
207function
208returns
209.Dv NULL
210after all keys have been returned.
211.Pp
212The
213.Fn dbm_error db
214function
215returns the
216.Va errno
217value of the most recent error.
218The
219.Fn dbm_clearerr db
220function
221resets this value to 0 and returns 0.
222.Pp
223The
224.Fn dbm_dirfno db
225function
226returns the file descriptor to the database.
227.Sh SEE ALSO
228.Xr open 2 ,
229.Xr dbopen 3 ,
230.Xr hash 3
231.Sh STANDARDS
232These functions (except
233.Fn dbm_dirfno )
234are included in the
235.St -susv2 .
236