xref: /dragonfly/lib/libc/db/man/dbm.3 (revision e6d22e9b) 
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: head/lib/libc/db/man/dbm.3 187918 2009-01-30 15:28:35Z gabor $
17.\"
18.Dd September 13, 2019
19.Dt DBM 3
20.Os
21.Sh NAME
22.Nm dbm_clearerr ,
23.Nm dbm_close ,
24.Nm dbm_delete ,
25.Nm dbm_dirfno ,
26.Nm dbm_error ,
27.Nm dbm_fetch ,
28.Nm dbm_firstkey ,
29.Nm dbm_nextkey ,
30.Nm dbm_open ,
31.Nm dbm_store
32.Nd database access functions
33.Sh LIBRARY
34.Lb libc
35.Sh SYNOPSIS
36.In fcntl.h
37.In ndbm.h
38.Ft DBM *
39.Fn dbm_open "const char *base" "int flags" "mode_t 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.In ndbm.h :
69.Bd -literal
70typedef struct {
71	char *dptr;
72	size_t 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.
127.Pp
128The
129.Fn dbm_store db key data flags
130function
131inserts or replaces an entry in the database.
132The
133.Fa flags
134argument
135is either
136.Dv DBM_INSERT
137or
138.Dv DBM_REPLACE .
139If
140.Fa flags
141is
142.Dv DBM_INSERT
143and the database already contains an entry for
144.Fa key ,
145that entry is not replaced.
146Otherwise the entry is replaced or inserted.
147The
148.Fn dbm_store
149function
150normally returns zero but returns 1 if the entry could not be
151inserted (because
152.Fa flags
153is
154.Dv DBM_INSERT ,
155and an entry with
156.Fa key
157already exists) or returns -1 and sets
158.Va errno
159if there were any errors.
160.Pp
161The
162.Fn dbm_fetch db key
163function
164returns
165.Dv NULL
166or the
167.Fa data
168corresponding to
169.Fa key .
170.Pp
171The
172.Fn dbm_delete db key
173function
174deletes the entry for
175.Fa key .
176The
177.Fn dbm_delete
178function
179normally returns zero but returns 1 if there was no entry with
180.Fa key
181in the database or returns -1 and sets
182.Va errno
183if there were any errors.
184.Pp
185The
186.Fn dbm_firstkey db
187function
188returns the first key in the database.
189The
190.Fn dbm_nextkey db
191function
192returns subsequent keys.
193The
194.Fn dbm_firstkey
195function
196must be called before
197.Fn dbm_nextkey .
198The order in which keys are returned is unspecified and may appear
199random.
200The
201.Fn dbm_nextkey
202function
203returns
204.Dv NULL
205after all keys have been returned.
206.Pp
207The
208.Fn dbm_error db
209function
210returns the
211.Va errno
212value of the most recent error.
213The
214.Fn dbm_clearerr db
215function
216resets this value to 0 and returns 0.
217.Pp
218The
219.Fn dbm_dirfno db
220function
221returns the file descriptor to the database.
222.Sh SEE ALSO
223.Xr open 2 ,
224.Xr dbopen 3 ,
225.Xr hash 3
226.Sh STANDARDS
227These functions (except
228.Fn dbm_dirfno )
229are included in the
230.St -susv2 .
231