xref: /dragonfly/lib/libc/db/man/dbm.3 (revision f746689a) 
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.5 2008/05/10 18:22:41 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 LIBRARY
37.Lb libc
38.Sh SYNOPSIS
39.In fcntl.h
40.In ndbm.h
41.Ft DBM *
42.Fn dbm_open "const char *base" "int flags" "int mode"
43.Ft void
44.Fn dbm_close "DBM *db"
45.Ft int
46.Fn dbm_store "DBM *db" "datum key" "datum data" "int flags"
47.Ft datum
48.Fn dbm_fetch "DBM *db" "datum key"
49.Ft int
50.Fn dbm_delete "DBM *db" "datum key"
51.Ft datum
52.Fn dbm_firstkey "DBM *db"
53.Ft datum
54.Fn dbm_nextkey "DBM *db"
55.Ft int
56.Fn dbm_error "DBM *db"
57.Ft int
58.Fn dbm_clearerr "DBM *db"
59.Ft int
60.Fn dbm_dirfno "DBM *db"
61.Sh DESCRIPTION
62Database access functions.
63These functions are implemented using
64.Xr dbopen 3
65with a
66.Xr hash 3
67database.
68.Pp
69.Vt datum
70is declared in
71.In ndbm.h :
72.Bd -literal
73typedef struct {
74	char *dptr;
75	int dsize;
76} datum;
77.Ed
78.Pp
79The
80.Fn dbm_open base flags mode
81function
82opens or creates a database.
83The
84.Fa base
85argument
86is the basename of the file containing
87the database; the actual database has a
88.Pa .db
89suffix.
90I.e., if
91.Fa base
92is
93.Qq Li /home/me/mystuff
94then the actual database is in the file
95.Pa /home/me/mystuff.db .
96The
97.Fa flags
98and
99.Fa mode
100arguments
101are passed to
102.Xr open 2 .
103.Pq Dv O_RDWR | O_CREAT
104is a typical value for
105.Fa flags ;
106.Li 0660
107is a typical value for
108.Fa mode .
109.Dv O_WRONLY
110is not allowed in
111.Fa flags .
112The pointer returned by
113.Fn dbm_open
114identifies the database and is the
115.Fa db
116argument to the other functions.
117The
118.Fn dbm_open
119function
120returns
121.Dv NULL
122and sets
123.Va errno
124if there were any errors.
125.Pp
126The
127.Fn dbm_close db
128function
129closes the database.
130The
131.Fn dbm_close
132function
133normally returns zero.
134.Pp
135The
136.Fn dbm_store db key data flags
137function
138inserts or replaces an entry in the database.
139The
140.Fa flags
141argument
142is either
143.Dv DBM_INSERT
144or
145.Dv DBM_REPLACE .
146If
147.Fa flags
148is
149.Dv DBM_INSERT
150and the database already contains an entry for
151.Fa key ,
152that entry is not replaced.
153Otherwise the entry is replaced or inserted.
154The
155.Fn dbm_store
156function
157normally returns zero but returns 1 if the entry could not be
158inserted (because
159.Fa flags
160is
161.Dv DBM_INSERT ,
162and an entry with
163.Fa key
164already exists) or returns -1 and sets
165.Va errno
166if there were any errors.
167.Pp
168The
169.Fn dbm_fetch db key
170function
171returns
172.Dv NULL
173or the
174.Fa data
175corresponding to
176.Fa key .
177.Pp
178The
179.Fn dbm_delete db key
180function
181deletes the entry for
182.Fa key .
183The
184.Fn dbm_delete
185function
186normally returns zero but returns 1 if there was no entry with
187.Fa key
188in the database or returns -1 and sets
189.Va errno
190if there were any errors.
191.Pp
192The
193.Fn dbm_firstkey db
194function
195returns the first key in the database.
196The
197.Fn dbm_nextkey db
198function
199returns subsequent keys.
200The
201.Fn dbm_firstkey
202function
203must be called before
204.Fn dbm_nextkey .
205The order in which keys are returned is unspecified and may appear
206random.
207The
208.Fn dbm_nextkey
209function
210returns
211.Dv NULL
212after all keys have been returned.
213.Pp
214The
215.Fn dbm_error db
216function
217returns the
218.Va errno
219value of the most recent error.
220The
221.Fn dbm_clearerr db
222function
223resets this value to 0 and returns 0.
224.Pp
225The
226.Fn dbm_dirfno db
227function
228returns the file descriptor to the database.
229.Sh SEE ALSO
230.Xr open 2 ,
231.Xr dbopen 3 ,
232.Xr hash 3
233.Sh STANDARDS
234These functions (except
235.Fn dbm_dirfno )
236are included in the
237.St -susv2 .
238