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