summaryrefslogtreecommitdiffabout
path: root/doc/gdbmtool.1
blob: e6a8f2a8515e6bfdae8d60cfa8df7799d9704b3a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
.\" This file is part of GDBM.
.\" Copyright (C) 2013 Free Software Foundation, Inc.
.\"
.\" GDBM is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 3, or (at your option)
.\" any later version.
.\"
.\" GDBM is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public License
.\" along with GDBM. If not, see <http://www.gnu.org/licenses/>. */
.TH GDBM_DUMP 1 "May 8, 2013" "GDBM" "GDBM User Reference"
.SH NAME
gdbmtool \- examine and modify a GDBM database
.SH SYNOPSIS
\fBgdbmtool\fR [\fB\-lmnqrs\fR] [\fB\-b\fR \fISIZE\fR] [\fB\-c\fR \fISIZE\fR]\
 [\fB\-g\fR \fIFILE\fR] [\fB\-\-block\-size\fR=\fISIZE\fR]
         [\fB\-\-cache\-size\fR=\fISIZE\fR] [\fB\-\-newdb\fR]\
 [\fB\-\-no\-lock\fR] [\fB\-\-no\-mmap\fR]
         [\fB\-\-quiet\fR] [\fB\-\-read\-only\fR] [\fB\-\-synchronize\fR]\
 [\fIDBFILE\fR]
.sp
\fBgdbmtool\fR [\fB\-Vh\fR] ][\fB\-\-help\fR] [\fB\-\-usage\fR] [\fB\-\-version\fR]
.SH DESCRIPTION
The
.B gdbmtool
utility allows you to view and modify an existing GDBM database or to
create a new one.
.PP
The \fIDBFILE\fR argument supplies the name of the database to open.
If not supplied, the default name
.B junk.gdbm
is used instead.
If the named database does not exist, it will be created.  An existing
database can be cleared (i.e. all records removed from it) using the
\fB\-\-newdb\fR option (see below).
.PP
After successful startup,
.B gdbmtool
starts a loop, in which it reads
commands from the user, executes them and prints the results on the
standard output.  If the standard input is attached to a console,
the program runs in interactive mode.
.PP
The program terminates when the
.B quit
command is given, or end-of-file is detected on its standard input.
.PP
A
.B gdbmtool
command consists of a command verb, optionally
followed by one or more arguments, separated by any amount of white
space.  A command verb can be entered either in full or in an
abbreviated form, as long as that abbreviation does not match any other
verb.  Many command verbs have also one-letter abbreviation which can
be used instead.
.SH OPTIONS
.TP
\fB\-b\fR, \fB\-\-block\-size\fR=\fISIZE\fR
Set block size.
.TP
\fB\-c\fR, \fB\-\-cache\-size\fR=\fISIZE\fR
Set cache size.
.TP
\fB\-l\fR, \fB\-\-no\-lock\fR
Disable file locking.
.TP
\fB\-m\fR, \fB\-\-no\-mmap\fR
Do not use
.BR mmap (2).
.TP
\fB\-n\fR, \fB\-\-newdb\fR
Create the database, truncating it if it already exists.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Don't print initial banner.
.TP
\fB\-r\fR, \fB\-\-read\-only\fR
Open database in read-only mode.
.TP
\fB\-s\fR, \fB\-\-synchronize\fR
Synchronize to disk after each write.
.TP
\fB\-h\fR, \fB\-\-help\fR
Print a short usage summary.
.TP
\fB\-\-usage\fR
Print a list of available options.
.TP
\fB\-V\fR, \fB\-\-version\fR
Print program version
.SH SHELL COMMANDS
For command verbs that have single-letter abbreviations, these are
printed after a comma.  Either command verb or its abbreviation must
be used, but not both.
.TP
.BR avail ", " A
Print the "
.BR "avail list" .
.TP
\fBbucket\fR, \fBB\fR \fINUM\fR
Print the bucket number \fINUM\fR.
.TP
.BR cache ", " K
Print the bucket cache.
.TP
.BR count ", " c
Print the number of entries in the database.
.TP
.BR current ", " C
Print the current bucket.
.TP
.BR data-zero ", " Z
Toggle data nul-termination.  Use
.B status
to examine the current status.
.TP
\fBdelete\fR, \fBd\fR \fIKEY\fR
Delete entry with the given \fIKEY\fR.
.TP
.BR dir ", " D
Print hash directory.
.TP
\fBexport\fR, \fBe\fR \fIFILE\-NAME\fR [\fBtruncate\fR] [\fBbinary\fR|\fBascii\fR]
Export the database to the flat file \fIFILE\-NAME\fR.  This is equivalent to
.BR gdbm_dump (1).

This command will not overwrite an existing file, unless the 
.B truncate
parameter is also given.  Another optional parameter determines the type of
the dump (*note Flat files::).  By default, ASCII dump will be created.
.TP
\fBfetch\fR, \fBf\fR \fIKEY\fR
Fetch and display the record with the given \fIKEY\fR.
.TP
.BR first ", " 1
Fetch and display the first record in the database.  Subsequent
records can be fetched using the
.B next
command (see below).
.TP
\fBhash\fR, \fBH\fR \fIKEY\fR
Compute and display hash value for the given \fIKEY\fR.
.TP
.BR header ", " F
Print file header.
.TP
.BR help ", " ?
Print a concise command summary, showing each command letter and
verb with its parameters and a short description of what it does.
Optional arguments are enclosed in square brackets.
.TP
\fBimport\fR, \fBi\fR \fIFILE\-NAME\fR [\fBreplace\fR] [\fBnometa\fR]
Import data from a flat dump file \fIFILE\-NAME\fR.
If the
.B replace
argument is given, any records with the same keys as the already
existing ones will replace them.  The
.B nometa
argument turns off restoring meta-information from the dump file.
.TP
.BR key-zero ", " z
Toggle key nul-termination.  Use
.B status
to inspect the current state.
.TP
\fBlist\fR, \fBl\fR
List the contents of the database.
.TP
\fBnext\fR, \fBn\fR [\fIKEY\fR]
Sequential access: fetch and display the next record.  If the \fIKEY\fR is
given, the record following the one with this key will be fetched.
.TP
\fBprompt\fR \fITEXT\fR
Changes the command prompt to the string \fITEXT\fR.  The string can
contain
.BR "escape sequences" ,
the special entities consisting of the
.B %
character followed by another character.  These sequences are
replaced in the generated prompt as follows:
.sp
.nf
.ta 8n 20n
.ul
	Sequence	Expansion
	\fB%f\fR	name of the db file
	\fB%%\fR	\fB%\fR
.fi
.TP
.BR quit ", " q
Close the database and quit the utility.
.TP
\fBread\fR, \fB<\fR \fIFILE\fR [\fBreplace\fR]
Read entries from \fIFILE\fR and store them in the database.  If the
.B replace
parameter is given, any existing records with matching keys will be replaced.
.TP
.BR reorganize ", " r
Reorganize the database.
.TP
.BR status ", " S
Print current program status.  The following example shows the
information displayed:
.sp
.nf
.if +2
Database file: junk.gdbm
Zero terminated keys: yes
Zero terminated data: yes
.fi
.TP
\fBstore\fR, \fBs\fR \fIKEY\fR \fIDATA\fR
Store the \fIDATA\fR with the given \fIKEY\fR in the database.  If the
\fIKEY\fR already exists, its data will be replaced.
.TP
.BR version ", " v
Print the version of
.BR gdbm .
.SH "SEE ALSO"
.BR gdbm_dump (1),
.BR gdbm_load (1),
.BR gdbm (3).
.SH "REPORTING BUGS"
Report bugs to <bug\-gdbm@gnu.org>.
.SH COPYRIGHT
Copyright \(co 2013 Free Software Foundation, Inc
.br
.na
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
.br
.ad
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
.\" Local variables:
.\" eval: (add-hook 'write-file-hooks 'time-stamp)
.\" time-stamp-start: ".TH GDBM[A-Z_-]* 1 \""
.\" time-stamp-format: "%:B %:d, %:y"
.\" time-stamp-end: "\""
.\" time-stamp-line-limit: 20
.\" end:

Return to:

Send suggestions and report system problems to the System administrator.