[apple/libc.git] / db / man / dbm.3

.\" Copyright (c) 1999 Tim Singletary
.\" No copyright is claimed.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/lib/libc/db/man/dbm.3,v 1.5 2001/10/01 16:08:50 ru Exp $
.\"
.\" Note: The date here should be updated whenever a non-trivial
.\" change is made to the manual page.
.Dd July 7, 1999
.Dt DBM 3
.Os
.Sh NAME
.Nm dbm_clearerr ,
.Nm dbm_close ,
.Nm dbm_delete ,
.Nm dbm_dirfno ,
.Nm dbm_error ,
.Nm dbm_fetch ,
.Nm dbm_firstkey ,
.Nm dbm_nextkey ,
.Nm dbm_open ,
.Nm dbm_store
.Nd database access functions
.Sh SYNOPSIS
.In fcntl.h
.In ndbm.h
.Ft DBM *
.Fn dbm_open "const char *base" "int flags" "int mode"
.Ft void
.Fn dbm_close "DBM *db"
.Ft int
.Fn dbm_store "DBM *db" "datum key" "datum data" "int flags"
.Ft datum
.Fn dbm_fetch "DBM *db" "datum key"
.Ft int
.Fn dbm_delete "DBM *db" "datum key"
.Ft datum
.Fn dbm_firstkey "DBM *db"
.Ft datum
.Fn dbm_nextkey "DBM *db"
.Ft int
.Fn dbm_error "DBM *db"
.Ft int
.Fn dbm_clearerr "DBM *db"
.Ft int
.Fn dbm_dirfno "DBM *db"
.Sh DESCRIPTION
Database access functions.
These functions are implemented using
.Xr dbopen 3
with a
.Xr hash 3
database.
.Pp
.Vt datum
is declared in
.Aq Pa ndbm.h :
.Bd -literal
typedef struct {
	char *dptr;
	int dsize;
} datum;
.Ed
.Pp
.Fn dbm_open base flags mode
opens or creates a database.
.Fa base
is the basename of the file containing
the database; the actual database has a
.Pa .db
suffix.
I.e., if
.Fa base
is
.Qq Li /home/me/mystuff
then the actual database is in the file
.Pa /home/me/mystuff.db .
.Fa flags
and
.Fa mode
are passed to
.Xr open 2 .
.Pq Dv O_RDWR | O_CREAT
is a typical value for
.Fa flags ;
.Li 0660
is a typical value for
.Fa mode .
.Dv O_WRONLY
is not allowed in
.Fa flags .
The pointer returned by
.Fn dbm_open
identifies the database and is the
.Fa db
argument to the other functions.
.Fn dbm_open
returns
.Dv NULL
and sets
.Va errno
if there were any errors.
.Pp
.Fn dbm_close db
closes the database.
.Fn dbm_close
normally returns zero.
.Pp
.Fn dbm_store db key data flags
inserts or replaces an entry in the database.
.Fa flags
is either
.Dv DBM_INSERT
or
.Dv DBM_REPLACE .
If
.Fa flags
is
.Dv DBM_INSERT
and the database already contains an entry for
.Fa key ,
that entry is not replaced.
Otherwise the entry is replaced or inserted.
.Fn dbm_store
normally returns zero but returns 1 if the entry could not be
inserted (because
.Fa flags
is
.Dv DBM_INSERT ,
and an entry with
.Fa key
already exists) or returns -1 and sets
.Va errno
if there were any errors.
.Pp
.Fn dbm_fetch db key
returns
.Dv NULL
or the
.Fa data
corresponding to
.Fa key .
.Pp
.Fn dbm_delete db key
deletes the entry for
.Fa key .
.Fn dbm_delete
normally returns zero but returns 1 if there was no entry with
.Fa key
in the database or returns -1 and sets
.Va errno
if there were any errors.
.Pp
.Fn dbm_firstkey db
returns the first key in the database.
.Fn dbm_nextkey db
returns subsequent keys.
.Fn db_firstkey
must be called before
.Fn dbm_nextkey .
The order in which keys are returned is unspecified and may appear
random.
.Fn dbm_nextkey
returns
.Dv NULL
after all keys have been returned.
.Pp
.Fn dbm_error db
returns the
.Va errno
value of the most recent error.
.Fn dbm_clearerr db
resets this value to 0 and returns 0.
.Pp
.Fn dbm_dirfno db
returns the file descriptor to the database.
.Sh SEE ALSO
.Xr open 2 ,
.Xr dbopen 3 ,
.Xr hash 3
.Sh STANDARDS
These functions (except
.Fn dbm_dirfno )
are included in the
.St -susv2 .
Commit	Line	Data
5b2abdfb A	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.5 2001/10/01 16:08:50 ru 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
	59	Database access functions.
	60	These functions are implemented using
	61	.Xr dbopen 3
	62	with a
	63	.Xr hash 3
	64	database.
65	.Pp
66	.Vt datum
67	is declared in
68	.Aq Pa ndbm.h :
69	.Bd -literal
70	typedef struct {
71	char *dptr;
72	int dsize;
73	} datum;
74	.Ed
75	.Pp
76	.Fn dbm_open base flags mode
77	opens or creates a database.
78	.Fa base
79	is the basename of the file containing
80	the database; the actual database has a
81	.Pa .db
82	suffix.
83	I.e., if
84	.Fa base
85	is
86	.Qq Li /home/me/mystuff
87	then the actual database is in the file
88	.Pa /home/me/mystuff.db .
89	.Fa flags
90	and
91	.Fa mode
92	are passed to
93	.Xr open 2 .
94	.Pq Dv O_RDWR \| O_CREAT
95	is a typical value for
96	.Fa flags ;
97	.Li 0660
98	is a typical value for
99	.Fa mode .
100	.Dv O_WRONLY
101	is not allowed in
102	.Fa flags .
103	The pointer returned by
104	.Fn dbm_open
105	identifies the database and is the
106	.Fa db
107	argument to the other functions.
108	.Fn dbm_open
109	returns
110	.Dv NULL
111	and sets
112	.Va errno
113	if there were any errors.
114	.Pp
115	.Fn dbm_close db
116	closes the database.
117	.Fn dbm_close
118	normally returns zero.
119	.Pp
120	.Fn dbm_store db key data flags
121	inserts or replaces an entry in the database.
122	.Fa flags
123	is either
124	.Dv DBM_INSERT
125	or
126	.Dv DBM_REPLACE .
127	If
128	.Fa flags
129	is
130	.Dv DBM_INSERT
131	and the database already contains an entry for
132	.Fa key ,
133	that entry is not replaced.
134	Otherwise the entry is replaced or inserted.
135	.Fn dbm_store
136	normally returns zero but returns 1 if the entry could not be
137	inserted (because
138	.Fa flags
139	is
140	.Dv DBM_INSERT ,
141	and an entry with
142	.Fa key
143	already exists) or returns -1 and sets
144	.Va errno
145	if there were any errors.
146	.Pp
147	.Fn dbm_fetch db key
148	returns
149	.Dv NULL
150	or the
151	.Fa data
152	corresponding to
153	.Fa key .
154	.Pp
155	.Fn dbm_delete db key
156	deletes the entry for
157	.Fa key .
158	.Fn dbm_delete
159	normally returns zero but returns 1 if there was no entry with
160	.Fa key
161	in the database or returns -1 and sets
162	.Va errno
163	if there were any errors.
164	.Pp
165	.Fn dbm_firstkey db
166	returns the first key in the database.
167	.Fn dbm_nextkey db
168	returns subsequent keys.
169	.Fn db_firstkey
170	must be called before
171	.Fn dbm_nextkey .
172	The order in which keys are returned is unspecified and may appear
173	random.
174	.Fn dbm_nextkey
175	returns
176	.Dv NULL
177	after all keys have been returned.
178	.Pp
179	.Fn dbm_error db
180	returns the
181	.Va errno
182	value of the most recent error.
183	.Fn dbm_clearerr db
184	resets this value to 0 and returns 0.
185	.Pp
186	.Fn dbm_dirfno db
187	returns the file descriptor to the database.
188	.Sh SEE ALSO
189	.Xr open 2 ,
190	.Xr dbopen 3 ,
191	.Xr hash 3
192	.Sh STANDARDS
193	These functions (except
194	.Fn dbm_dirfno )
195	are included in the
196	.St -susv2 .